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

collections_search e file_search na API de Respostas

Aula 11 de 16 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Integrar a pesquisa diretamente nas conversas
  2. A ferramenta collections_search
  3. A ferramenta file_search
  4. Dois mecanismos, duas estruturas de custos
  5. Combinar várias ferramentas
  6. Refinar o comportamento da ferramenta
  7. Pontos-chave

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.

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.

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

Aspetocollections_searchfile_search / attachment_search
OrigemColeção(ões) indexada(s)Ficheiro(s) individual(is)
DeclaraçãoExplícita em toolsAutomática com input_file
IndexaçãoPré-computadaEm tempo real
Custo$2,50 / 1.000$10 / 1.000
DesempenhoRápido (índice existente)Mais lento (indexação em tempo real)
Caso de usoBase de conhecimento permanenteAná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_search permite que o Grok consulte automaticamente as suas coleções durante uma conversa
  • file_search / attachment_search ativa-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_search com web_search e outras ferramentas
  • O Grok escolhe automaticamente quais as ferramentas a utilizar com base na pergunta