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

Pesquisa de Ficheiros: Indexar e Consultar Documentos

Aula 7 de 20 Programador
Nesta página
  1. Pesquisa de Ficheiros: Indexar e Consultar Documentos
  2. Criar um Arquivo Vetorial
  3. Carregar e Indexar Ficheiros
  4. Consultar com Pesquisa de Ficheiros
  5. Examinar Resultados da Pesquisa
  6. Configurar a Pesquisa
  7. Gerir o Ciclo de Vida do Arquivo Vetorial
  8. Exemplo Completo: Assistente de Documentação
  9. Pontos-chave

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_results controla a profundidade da pesquisa
  • Metadados e filtros permitem pesquisas direcionadas
  • Monitore o estado da indexação antes de consultar