input_file e attachment_search na API de Respostas
Nesta página
Dois caminhos para o mesmo bloco
A API de Respostas do Grok aceita um documento de duas formas: através de file_id, que significa um ficheiro que carregou anteriormente, ou através de file_url, um endereço público que a xAI vai buscar no momento do pedido. O bloco usa o mesmo nome em ambos os casos, input_file, e o processamento subsequente é idêntico: o Grok ativa a ferramenta attachment_search e extrai as passagens que respondem à sua pergunta. O que muda é o ciclo de vida do documento, a sua confidencialidade e o custo de cada chamada repetida.
O caminho do file_id
Depois de enviar o ficheiro via POST /v1/files, referencia-o pelo seu identificador, juntamente com a sua pergunta em texto simples:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123"
},
{
"type": "input_text",
"text": "What are the main risks mentioned in this report?"
}
]
}
Este caminho faz sentido em três situações. A primeira são consultas repetidas: se a sua equipa jurídica fizer quinze perguntas sucessivas sobre o mesmo contrato, um único carregamento seguido de quinze referências é mais eficiente do que quinze transferências do mesmo PDF. A segunda é a confidencialidade, quando o documento não deve ficar exposto atrás de um URL acessível a qualquer pessoa com o link. A terceira é a arquitetura da sua aplicação: se os ficheiros forem pré-carregados durante a ingestão noturna, os seus pedidos lidam apenas com identificadores.
O caminho do file_url
Quando o documento já está publicado nalgum lugar, o carregamento torna-se um passo desnecessário e pode apontar diretamente para o endereço:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_url": "https://exemple.com/specifications-api.pdf"
},
{
"type": "input_text",
"text": "Summarize the endpoints described in this documentation."
}
]
}
Os casos de uso típicos incluem documentação aberta que não tem razão para armazenar, um ficheiro alojado na sua própria infraestrutura atrás de um URL temporário, ou um teste rápido onde quer verificar uma hipótese sem configurar toda uma pipeline de carregamento.
Três limitações acompanham esta conveniência, e todas lhe custam caro em produção. O URL deve ser verdadeiramente público, sem autenticação: um endereço protegido por um token ou cookie devolve uma página de erro à xAI, que o modelo analisará diligentemente em vez do seu documento. O download adiciona tempo ao processamento do pedido, tornando os PDFs grandes significativamente mais lentos do que com file_id. Finalmente, não existe cache do lado da xAI: cada chamada volta a descarregar o ficheiro, pelo que um único documento consultado cinquenta vezes por dia atravessa a rede cinquenta vezes.
O que faz o attachment_search
Assim que um input_file aparece no seu pedido, o Grok aciona o attachment_search sem qualquer configuração da sua parte. O processamento ocorre em quatro etapas:
- Extração de conteúdo do ficheiro: texto, tabelas, estrutura
- Indexação temporária deste conteúdo, pela duração do pedido
- Pesquisa de passagens relevantes com base na sua pergunta
- Injeção de excertos no contexto do modelo
Concentre-se no adjetivo “temporária” na segunda etapa, porque explica uma diferença de custos que muitos descobrem tarde demais: o índice é reconstruído em cada chamada e desaparece depois. Este é precisamente o problema que as coleções resolvem com a indexação persistente. Note também que o modelo cita as passagens que realmente utilizou na sua resposta, permitindo-lhe verificar o seu trabalho em vez de confiar cegamente na sua palavra.
Combinação de múltiplos documentos
Nada o obriga a limitar-se a um ficheiro por pedido. Ao empilhar vários blocos input_file, pede ao modelo que raciocine sobre o conjunto:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_rapport_q1"
},
{
"type": "input_file",
"file_id": "file_rapport_q2"
},
{
"type": "input_text",
"text": "Compare the Q1 and Q2 results."
}
]
}
O Grok analisa ambos os documentos e cruza as informações para responder, o que abre a porta a comparações trimestrais, revisões de versões sucessivas de contratos ou confrontos entre uma especificação e a sua implementação.
Escolher entre os dois
| Critério | file_id | file_url |
|---|---|---|
| Carregamento prévio | Sim | Não |
| Ficheiro confidencial | Recomendado | Desaconselhado |
| Consultas repetidas | Eficiente (1 carregamento) | Lento (redownload) |
| Ficheiro público | Possível | Ideal |
| Gestão do ciclo de vida | Controla você | Depende do anfitrião |
Pontos-chave
input_filecomfile_idreferencia um ficheiro carregado,file_urlum documento público- A ferramenta
attachment_searchativa-se automaticamente para extrair conteúdo relevante - Pode combinar múltiplos ficheiros num único pedido
- Prefira
file_idpara ficheiros confidenciais ou frequentemente consultados - Prefira
file_urlpara documentos públicos ou testes rápidos