Pesquisa de Ficheiros: Indexar e Consultar Documentos
Nesta página
Pesquisa de Ficheiros: Indexar e Consultar Documentos
A Pesquisa de Ficheiros permite ao modelo procurar nos seus documentos privados. Carrega ficheiros para um arquivo vetorial e o modelo consulta-os automaticamente sempre que necessita de informações específicas. Esta é a base do RAG (Recuperação Aumentada por Geração) integrada diretamente na API da OpenAI.
Criar um Arquivo Vetorial
O arquivo vetorial é a unidade organizacional da Pesquisa de Ficheiros e a estrutura que escolher aqui permanecerá consigo durante muito tempo. Um único arquivo para toda a empresa é fácil de administrar, mas mistura documentos com vocabulários não relacionados, o que degrada a relevância. Arquivos separados por equipa ou domínio exigem um pouco mais de gestão, mas tornam cada pesquisa significativamente mais precisa. Na dúvida, separe-os: fundir mais tarde é mais fácil do que desembaraçar uma confusão.
from openai import OpenAI
client = OpenAI()
# Create the vector store
vector_store = client.vector_stores.create(
name="product-documentation"
)
print(f"Vector store created: {vector_store.id}")
Carregar e Indexar Ficheiros
A indexação é assíncrona e esta é a fonte de erros mais comum na primeira tentativa: adiciona ficheiros, consulta imediatamente e o modelo diz que não encontrou nada — não porque a pesquisa falhou, mas porque nada foi ainda indexado. Verifique sempre o estado antes de consultar, como mostrado na secção do ciclo de vida.
Uma nota sobre formatos: a lista é ampla, mas nem todos os ficheiros são iguais. Um PDF gerado a partir de um processador de texto extrai-se limparmente; um PDF digitalizado sem camada de texto não acrescenta nada, uma vez que, literalmente, não há palavras para indexar.
import os
# Upload a single file
with open("user-guide.pdf", "rb") as f:
file_obj = client.files.create(file=f, purpose="assistants")
# Attach to the vector store
client.vector_stores.files.create(
vector_store_id=vector_store.id,
file_id=file_obj.id
)
# Batch upload
folder = "./documentation/"
for filename in os.listdir(folder):
path = os.path.join(folder, filename)
if os.path.isfile(path):
with open(path, "rb") as f:
file_obj = client.files.create(file=f, purpose="assistants")
client.vector_stores.files.create(
vector_store_id=vector_store.id,
file_id=file_obj.id
)
print(f"Indexed: {filename}")
Consultar com Pesquisa de Ficheiros
A chamada é intencionalmente direta: declara a ferramenta, faz a sua pergunta e o modelo decide se deve pesquisar. Todo o trabalho de RAG — fragmentação, vetorização, classificação e injeção no contexto — ocorre no servidor. Isto poupa tempo considerável no arranque e a próxima lição cobre as definições que precisa de conhecer quando os valores padrão não forem suficientes.
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the refund procedure for premium clients?",
tools=[{
"type": "file_search",
"vector_store_ids": [vector_store.id]
}]
)
print(response.output_text)
O modelo procura automaticamente nos seus documentos e formula uma resposta com base no conteúdo que encontra.
Examinar Resultados da Pesquisa
As anotações são o que distingue uma resposta verificável de uma mera afirmação. Disponibilize-as aos seus utilizadores: numa base de conhecimento interna, a capacidade de rastrear até ao documento original muda completamente o nível de confiança no sistema — e ajuda-o a detetar casos em que o modelo falhou.
response = client.responses.create(
model="gpt-5.6-terra",
input="What SLAs are guaranteed in the contract?",
tools=[{
"type": "file_search",
"vector_store_ids": [vector_store.id]
}]
)
# Iterate through annotations
for item in response.output:
if item.type == "message":
for block in item.content:
if hasattr(block, "annotations"):
for ann in block.annotations:
if ann.type == "file_citation":
print(f"File: {ann.file_id}")
print(f"Position: {ann.start_index}-{ann.end_index}")
Configurar a Pesquisa
Número de Resultados
Aumentar o número de passagens não melhora mecanicamente a resposta. Além de cerca de dez, excertos pouco relevantes diluem os bons e consomem contexto faturado. Aumente este valor apenas quando a resposta estiver visivelmente incompleta, não como princípio geral.
response = client.responses.create(
model="gpt-5.6-terra",
input="List all penalty clauses in the contract",
tools=[{
"type": "file_search",
"vector_store_ids": [vector_store.id],
"max_num_results": 20 # Default: 5, max: 50
}]
)
Filtragem por Metadados
Os metadados são a alavanca mais subutilizada para a precisão. Filtrar por ano, departamento ou tipo de documento antes da pesquisa vetorial elimina o ruído à partida que a classificação teria otherwise de filtrar. Isto também permite responder «de acordo com o procedimento atual» em vez de misturar três versões sucessivas do mesmo documento.
# Upload with metadata
with open("contract-2026.pdf", "rb") as f:
file_obj = client.files.create(file=f, purpose="assistants")
client.vector_stores.files.create(
vector_store_id=vector_store.id,
file_id=file_obj.id,
attributes={
"doc_type": "contract",
"year": 2026,
"client": "acme-corp"
}
)
# Filtered search
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the due date?",
tools=[{
"type": "file_search",
"vector_store_ids": [vector_store.id],
"filters": {
"type": "eq",
"key": "doc_type",
"value": "contract"
}
}]
)
Filtros Compostos
Combine múltiplos critérios utilizando operadores lógicos:
response = client.responses.create(
model="gpt-5.6-terra",
input="Summarize contractual obligations for 2026",
tools=[{
"type": "file_search",
"vector_store_ids": [vector_store.id],
"filters": {
"type": "and",
"filters": [
{"type": "eq", "key": "doc_type", "value": "contract"},
{"type": "gte", "key": "year", "value": 2026}
]
}
}]
)
Gerir o Ciclo de Vida do Arquivo Vetorial
Monitorizar a Indexação
# Check vector store status
vs = client.vector_stores.retrieve(vector_store.id)
print(f"Status: {vs.status}")
print(f"Files: {vs.file_counts.completed} indexed, "
f"{vs.file_counts.in_progress} in progress, "
f"{vs.file_counts.failed} failed")
Remover Ficheiros Obsoletos
# List files in the vector store
files = client.vector_stores.files.list(vector_store.id)
for f in files.data:
print(f"{f.id} - {f.status}")
# Detach a file
client.vector_stores.files.delete(
vector_store_id=vector_store.id,
file_id="file_abc123"
)
Exemplo Completo: Assistente de Documentação
def documentation_assistant(question: str, vs_id: str) -> dict:
"""Assistant that answers based on internal documentation."""
response = client.responses.create(
model="gpt-5.6-terra",
instructions=(
"You are a documentation assistant. Answer solely based on the "
"provided documents. If the information is not in the documents, "
"state that clearly. Cite your sources."
),
input=question,
tools=[{
"type": "file_search",
"vector_store_ids": [vs_id],
"max_num_results": 10
}]
)
return {
"answer": response.output_text,
"model": response.model,
"tokens": response.usage.total_tokens
}
Pontos-chave
- Crie um arquivo vetorial e carregue os seus ficheiros para ativar a Pesquisa de Ficheiros
- O modelo decide por si próprio quando deve procurar nos documentos
max_num_resultscontrola a profundidade da pesquisa- Metadados e filtros permitem pesquisas direcionadas
- Monitore o estado da indexação antes de consultar