collections_search e file_search na API de Respostas
Nesta página
Integrar a pesquisa diretamente nas conversas
O endpoint POST /v1/documents/search funciona bem para perguntas isoladas, mas deixa todo o trabalho de orquestração consigo: formular a consulta, recuperar excertos, injetá-los num prompt e chamar o modelo. A API de Respostas inverte este ónus. Ao declarar as suas coleções como uma ferramenta, permite que o Grok decida quando pesquisar, o que procurar e como transformar isso numa resposta. Você passa de um pipeline que conduz manualmente para um assistente que pesquisa os seus documentos por si próprio.
A ferramenta collections_search
Só precisa de adicionar um objeto à lista tools para ativar este acesso:
response = await client.responses.create(
model="grok-4.5",
input="What is our paternity leave policy?",
tools=[
{
"type": "collections_search",
"collection_ids": ["col_rh_policies"]
}
]
)
Por detrás desta única chamada, o Grok analisa a pergunta, formula uma consulta de pesquisa adaptada à coleção, recupera passagens relevantes, resume-as e cita os documentos utilizados. Na prática, para a pergunta acima, ele traduzirá “licença de paternidade” numa pesquisa em col_rh_policies, reterá os parágrafos do acordo da empresa e devolverá um número de dias juntamente com a sua fonte, sem que você escreva uma única linha de lógica de recuperação.
A ferramenta file_search
Existe uma contraparte para ficheiros individuais, aqueles que não estão armazenados numa coleção. Não é necessário declará-la: ativa-se automaticamente assim que o seu pedido contiver um input_file.
response = await client.responses.create(
model="grok-4.5",
input=[
{
"type": "input_file",
"file_id": "file_contrat_abc"
},
{
"type": "input_text",
"text": "Does this contract contain a non-compete clause?"
}
]
)
É a ferramenta attachment_search, equivalente à file_search, que se ativa em segundo plano. Este comportamento implícito explica uma confusão comum: os utilizadores questionam-se por que razão declarar file_search em tools parece não ter efeito, quando é simplesmente redundante.
Dois mecanismos, duas estruturas de custos
| Aspeto | collections_search | file_search / attachment_search |
|---|---|---|
| Origem | Coleção(ões) indexada(s) | Ficheiro(s) individual(is) |
| Declaração | Explícita em tools | Automática com input_file |
| Indexação | Pré-computada | Em tempo real |
| Custo | $2,50 / 1.000 | $10 / 1.000 |
| Desempenho | Rápido (índice existente) | Mais lento (indexação em tempo real) |
| Caso de uso | Base de conhecimento permanente | Análise pontual |
A linha “Indexação” determina todas as outras. Uma coleção é indexada uma vez por todas, pelo que cada pergunta reutiliza esse trabalho: é rápido e faturado a $2,50 por mil chamadas. Um ficheiro anexado é indexado a cada pedido, daí a latência adicional e os $10 por mil. O contrato que o seu consultor jurídico analisa uma vez enquadra-se na segunda categoria; o repositório de RH consultado cem vezes por dia enquadra-se obviamente na primeira.
Combinar várias ferramentas
O verdadeiro benefício desta abordagem surge quando fornece ao Grok várias delas, permitindo-lhe selecionar as que servem a pergunta.
response = await client.responses.create(
model="grok-4.5",
input="Compare our internal policy with the latest European regulations on the subject.",
tools=[
{
"type": "collections_search",
"collection_ids": ["col_politiques_internes"]
},
{
"type": "web_search"
}
]
)
Esta pergunta exige dois movimentos sucessivos: o Grok consulta primeiro a coleção para encontrar a sua política interna, depois lança uma pesquisa na web para as regulamentações europeias atuais e, finalmente, contrasta as duas na sua resposta. Sem orquestração da sua parte, sem instrução if para decidir qual das duas fontes é relevante — e se a pergunta se focasse apenas na sua política interna, a web não teria sido utilizada.
Refinar o comportamento da ferramenta
Três parâmetros permitem-lhe afinar a pesquisa declarada em tools.
tools=[
{
"type": "collections_search",
"collection_ids": ["col_docs_1", "col_docs_2"],
"max_results": 10,
"retrieval_mode": "hybrid"
}
]
- collection_ids: consultar várias coleções simultaneamente
- max_results: limitar o número de resultados para reduzir o contexto injetado
- retrieval_mode: escolher o modo de pesquisa (híbrido por predefinição)
O parâmetro max_results merece atenção especial: cada excerto devolvido ocupa contexto e custa tokens. Num assistente de suporte onde as respostas cabem geralmente em dois ou três trechos, reduzir do valor predefinido para cinco resultados diminui o custo sem degradar a qualidade percecionada.
Preços atualizados a 5 de agosto de 2026 — os preços mudam regularmente: antes de calcular qualquer orçamento, verifique os preços atuais na página oficial de modelos e preços da xAI.
Pontos-chave
collections_searchpermite que o Grok consulte automaticamente as suas coleções durante uma conversafile_search/attachment_searchativa-se automaticamente para ficheiros individuais- As coleções são quatro vezes mais baratas e rápidas do que os anexos de ficheiros
- Pode combinar
collections_searchcomweb_searche outras ferramentas - O Grok escolhe automaticamente quais as ferramentas a utilizar com base na pergunta