O endpoint de pesquisa de documentos
Nesta página
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.
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,semanticouhybrid).
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/searchconsulta 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.