Ir para o conteúdo principal
Português— Escolher um idioma
Menu

O endpoint de pesquisa de documentos

Aula 9 de 16 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Consultar as suas bases de conhecimento
  2. Estrutura do pedido
  3. Ler a resposta
  4. Pesquisar em várias coleções
  5. Custo
  6. Pontos-chave

Consultar as suas bases de conhecimento

Até agora, construiu o contentor: coleções, documentos indexados, metadados. Nada disto importa se não souber como fazer uma pergunta. É essa a função do POST /v1/documents/search, que recebe uma consulta em linguagem natural e devolve os trechos dos seus documentos que melhor lhe respondem. Imagine uma equipa de apoio que recebe a pergunta “Qual é o prazo de desistência?”. Em vez de obrigar um agente a ler os termos e condições, envia a questão para o endpoint e recupera os três parágrafos úteis, completos com a sua pontuação e fonte.

POST
/v1/documents/search
3 modos
keyword, semantic, hybrid
$2.50
Per 1,000 calls
Multi
Multiple collections

Estrutura do pedido

A primeira coisa a reter, e isto é uma fonte comum de erros: este endpoint reside na API standard (api.x.ai), e não na API de Gestão que utilizou para criar coleções. A autenticação é feita com a sua chave de API habitual. O pedido mínimo resume-se a três campos.

curl -X POST https://api.x.ai/v1/documents/search \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I configure OAuth authentication?",
    "source": {
      "collection_ids": ["col_xyz789"]
    },
    "retrieval_mode": {
      "type": "hybrid"
    }
  }'

Parâmetros principais

  • query: a sua pergunta em linguagem natural. Quanto mais específica for a pergunta, mais relevantes serão os resultados.
  • source.collection_ids: um vetor de IDs de coleções a consultar. Pode pesquisar em várias coleções num único pedido.
  • retrieval_mode.type: o modo de pesquisa a utilizar (keyword, semantic ou hybrid).

Ler a resposta

A API não devolve documentos inteiros, mas sim fragmentos, os blocos criados durante a indexação, ordenados do mais relevante para o menos relevante.

{
  "results": [
    {
      "content": "To configure OAuth, start by...",
      "score": 0.92,
      "document_id": "file_abc123",
      "metadata": {
        "filename": "security-guide.pdf",
        "page": 12
      }
    },
    {
      "content": "The OAuth 2.0 flow uses...",
      "score": 0.87,
      "document_id": "file_def456",
      "metadata": {
        "filename": "api-reference.pdf",
        "page": 45
      }
    }
  ]
}

Cada entrada contém quatro informações:

  • content: o excerto de texto do documento.
  • score: uma pontuação de relevância entre 0 e 1.
  • document_id: o ID do ficheiro de origem.
  • metadata: os metadados do documento (nome, página, campos personalizados).

No exemplo acima, o primeiro excerto provém da página 12 do security-guide.pdf com uma pontuação de 0,92; o segundo da página 45 de outro ficheiro com 0,87. Estes dois valores são suficientes para construir uma interface que apresente a resposta e, logo abaixo, uma ligação “ver trecho original, página 12”. A pontuação atua como um limiar: muitas equipas descartam qualquer resultado abaixo de 0,5 em vez de deixarem o modelo raciocinar com base em ruído.

Pesquisar em várias coleções

Se collection_ids é um vetor, não é por acaso. Uma pergunta de um cliente mistura frequentemente vários universos documentais, e não quererá fazer três chamadas para depois fundir os resultados manualmente.

{
  "query": "Refund policy",
  "source": {
    "collection_ids": [
      "col_docs_produit",
      "col_faq",
      "col_conditions_generales"
    ]
  },
  "retrieval_mode": {
    "type": "hybrid"
  }
}

Aqui, a documentação do produto, as FAQ e os termos e condições são consultados em conjunto. Os resultados regressam fundidos e ordenados por pontuação, independentemente da sua coleção de origem: um excerto das FAQ com 0,94 ficará acima de um excerto dos T&C com 0,71. Cruza fontes heterogéneas numa única ida e volta à rede.

Custo

A pesquisa em coleções custa $2,50 por 1.000 chamadas, e esta taxa não muda consoante o número de coleções consultadas ou o tamanho dos documentos indexados. Compare isto com os anexos de ficheiros, aqueles ficheiros individuais passados via input_file, faturados a $10 por 1.000 chamadas: assim que consultar os mesmos documentos repetidamente, as coleções custam quatro vezes menos. Um assistente interno que lide com 20.000 perguntas por mês paga $50 com coleções contra $200 com anexos — e obtém resultados mais rápidos como bónus, uma vez que o índice já existe.

Preços atualizados a 5 de agosto de 2026 — os preços mudam regularmente: antes de qualquer cálculo orçamental, consulte a tabela de preços atual na página oficial de modelos e preços da xAI.

Pontos-chave

  • O endpoint POST /v1/documents/search consulta as suas coleções em linguagem natural.
  • Três modos de pesquisa disponíveis: keyword, semantic, hybrid.
  • Pode pesquisar em várias coleções simultaneamente.
  • Os resultados são ordenados por pontuação de relevância com o conteúdo da fonte.
  • O custo é de $2,50 por 1.000 chamadas, quatro vezes mais barato do que os anexos de ficheiros.