Python + IA: Fundamentos e Projetos Práticos
Uma IA pode escrever bem e ainda assim responder com informações desatualizadas, porque o modelo não conhece automaticamente os manuais, políticas e documentos internos da sua aplicação. O File Search resolve esse problema ao permitir que a Responses API pesquise uma base de arquivos antes de produzir a resposta.
Nesta aula, você vai criar uma pequena central de suporte em Python. O sistema receberá um manual, localizará os trechos relevantes e responderá com referências ao arquivo consultado. É uma evolução natural depois de aprender function calling em Python: em vez de executar uma função externa, o modelo usará uma ferramenta hospedada para recuperar conhecimento.
O que o File Search faz — e quando vale a pena usar
O File Search é uma ferramenta da Responses API que combina busca semântica e busca por palavras-chave. Os arquivos são organizados em um vector store, processados e recuperados conforme a pergunta. A ferramenta é hospedada pela OpenAI, portanto você não precisa implementar manualmente geração de embeddings, indexação, comparação vetorial e montagem do contexto.
Use esse recurso quando a resposta depender de uma coleção de documentos: central de ajuda, políticas comerciais, procedimentos operacionais, catálogo técnico, contratos padronizados ou documentação de produto. Ele é diferente de enviar um arquivo isolado em toda requisição: o vector store cria uma base reutilizável e evita reenviar o mesmo conteúdo a cada pergunta.
Também não é o mesmo que function calling. File Search consulta conhecimento; function calling executa uma ação, como buscar um pedido no banco ou abrir um chamado. Em uma aplicação real, as duas ferramentas podem trabalhar juntas.
Prepare o projeto e um documento de teste
Crie uma pasta vazia, configure um ambiente virtual e instale o SDK oficial. Se você ainda organiza dependências manualmente, veja também o guia de Python com uv e pyproject.toml.
uv init suporte-file-search
cd suporte-file-search
uv add openai python-dotenvSalve sua chave em um arquivo .env que não será enviado ao Git:
OPENAI_API_KEY=sua_chave_aquiAgora crie manual-suporte.txt. Em produção, o conteúdo virá de documentos reais; aqui usaremos regras simples para conseguir verificar a qualidade da recuperação.
POLÍTICA DE TROCAS — versão 3, agosto de 2026
Produtos físicos podem ser trocados em até 30 dias após o recebimento.
O item deve estar sem sinais de uso e acompanhado da nota fiscal.
Produtos digitais não são reembolsáveis após o primeiro acesso.
Casos de cobrança duplicada devem ser analisados em até 2 dias úteis.
O atendimento humano funciona de segunda a sexta, das 9h às 18h.Documentos com títulos claros, datas, seções curtas e linguagem consistente costumam produzir buscas melhores. Evite misturar versões conflitantes no mesmo arquivo sem identificar qual regra está vigente.
Envie o arquivo e crie o vector store
O primeiro script envia o documento pela Files API, cria o vector store e associa o arquivo à base. A documentação atual utiliza purpose="assistants" no upload. Depois da associação, aguarde o processamento antes de liberar perguntas na aplicação.
import os
import time
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
with open("manual-suporte.txt", "rb") as documento:
arquivo = client.files.create(
file=documento,
purpose="assistants",
)
base = client.vector_stores.create(name="Manual de suporte")
vinculo = client.vector_stores.files.create(
vector_store_id=base.id,
file_id=arquivo.id,
)
while vinculo.status == "in_progress":
time.sleep(2)
vinculo = client.vector_stores.files.retrieve(
vector_store_id=base.id,
file_id=arquivo.id,
)
if vinculo.status != "completed":
raise RuntimeError(f"Falha ao indexar: {vinculo.status}")
print("VECTOR_STORE_ID=", base.id)Guarde o identificador da base em uma variável de ambiente. Não recrie o vector store em toda execução: além de duplicar conteúdo, isso dificulta controle de versões e custos. Em um fluxo de implantação, a indexação deve ser uma etapa separada da aplicação que responde aos usuários.
Faça uma pergunta com a Responses API
Com a base pronta, inclua a ferramenta file_search e informe os vector stores permitidos. O parâmetro max_num_results limita quantos resultados serão recuperados; valores menores podem reduzir latência e tokens, mas um limite agressivo pode retirar contexto importante.
import os
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
client = OpenAI()
response = client.responses.create(
model="gpt-5.6",
input=(
"Responda somente com base no manual. "
"Qual é o prazo para troca de um produto físico e "
"quais condições precisam ser atendidas?"
),
tools=[{
"type": "file_search",
"vector_store_ids": [os.environ["VECTOR_STORE_ID"]],
"max_num_results": 3,
}],
include=["file_search_call.results"],
)
print(response.output_text)A resposta deverá mencionar os 30 dias, a ausência de sinais de uso e a nota fiscal. A saída também contém uma chamada file_search_call e uma mensagem com anotações do tipo file_citation. O parâmetro include acrescenta os resultados recuperados ao objeto retornado, algo útil para depuração, auditoria e avaliação.
Não confunda “há citação” com “a resposta está correta”. Exiba a fonte para o usuário e compare a afirmação com o trecho recuperado. Se sua automação precisa devolver dados estruturados para outro sistema, combine esta etapa com Structured Outputs e JSON validado.
Melhore relevância, escopo e segurança
A maior parte dos problemas de busca nasce na organização da base, não no prompt. Separe documentação por produto ou cliente, remova duplicatas e mantenha apenas versões vigentes. Em aplicações multiempresa, nunca dependa do texto da pergunta para isolar dados: use vector stores separados por tenant ou filtros de metadados controlados pelo servidor.
Os filtros permitem restringir resultados por atributos como categoria, região, versão ou status. Isso evita que uma pergunta sobre a política brasileira recupere uma regra de outro país. A escolha do filtro deve vir da identidade autenticada e das permissões da aplicação, e não de parâmetros livres enviados pelo navegador.
tools=[{
"type": "file_search",
"vector_store_ids": [os.environ["VECTOR_STORE_ID"]],
"filters": {
"type": "in",
"key": "categoria",
"value": ["suporte", "politicas_vigentes"],
},
}]Trate os documentos como dados sensíveis. Não faça upload de segredos, chaves, senhas ou informações pessoais sem necessidade e base legal. Defina responsáveis pela atualização, política de retenção e processo de exclusão. Registre qual versão do arquivo sustentou cada resposta importante.
Teste a qualidade antes de colocar em produção
Monte um conjunto de perguntas com respostas esperadas. Inclua casos fáceis, ambiguidades, informação inexistente e perguntas que deveriam ser recusadas. Avalie separadamente recuperação e geração: primeiro confirme se o trecho correto apareceu nos resultados; depois verifique se o modelo o interpretou sem inventar condições.
Um teste útil para este exemplo contém pelo menos estas perguntas:
- Qual é o prazo de troca para produto físico?
- Um produto digital acessado pode ser reembolsado?
- Em quanto tempo a cobrança duplicada é analisada?
- O suporte funciona no sábado?
- Qual é o prazo de garantia estendida? — a base não informa isso.
Para perguntas sem resposta documental, instrua o modelo a declarar a ausência da informação e encaminhar o caso. Monitore latência, quantidade de resultados, taxa de respostas fundamentadas e dúvidas que chegam ao atendimento humano. Ajuste max_num_results com dados reais, não por intuição.
Checklist de implementação e próximo passo
- Crie um vector store por domínio de conhecimento ou limite de acesso.
- Envie documentos limpos, versionados e com títulos descritivos.
- Aguarde a indexação terminar antes de aceitar consultas.
- Defina explicitamente os vector stores e filtros permitidos no servidor.
- Inclua os resultados durante testes para inspecionar a recuperação.
- Mostre citações e ofereça escalonamento quando a base não responder.
- Teste perguntas conhecidas, negativas, ambíguas e adversariais.
- Revise retenção, exclusão, custos e permissões periodicamente.
O File Search transforma uma coleção de documentos em uma fonte consultável pela IA sem exigir que você construa toda a infraestrutura de recuperação. O ganho real, porém, vem da disciplina: base bem governada, acesso restrito, perguntas de avaliação e fontes visíveis.
Como próximo passo, adapte o exemplo a um manual real e crie dez perguntas de teste antes de conectá-lo a uma interface. Continue acompanhando a série Python + IA: Fundamentos e Projetos Práticos para integrar essa busca a fluxos mais completos.
Referências oficiais: File Search na Responses API e Retrieval e vector stores.
