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

input_file e attachment_search na API de Respostas

Aula 4 de 16 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Dois caminhos para o mesmo bloco
  2. O caminho do file_id
  3. O caminho do file_url
  4. O que faz o attachment_search
  5. Combinação de múltiplos documentos
  6. Escolher entre os dois
  7. Pontos-chave

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.

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:

  1. Extração de conteúdo do ficheiro: texto, tabelas, estrutura
  2. Indexação temporária deste conteúdo, pela duração do pedido
  3. Pesquisa de passagens relevantes com base na sua pergunta
  4. 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ériofile_idfile_url
Carregamento prévioSimNão
Ficheiro confidencialRecomendadoDesaconselhado
Consultas repetidasEficiente (1 carregamento)Lento (redownload)
Ficheiro públicoPossívelIdeal
Gestão do ciclo de vidaControla vocêDepende do anfitrião

Pontos-chave

  • input_file com file_id referencia um ficheiro carregado, file_url um documento público
  • A ferramenta attachment_search ativa-se automaticamente para extrair conteúdo relevante
  • Pode combinar múltiplos ficheiros num único pedido
  • Prefira file_id para ficheiros confidenciais ou frequentemente consultados
  • Prefira file_url para documentos públicos ou testes rápidos