OpenAI Assistant Retrieval: guia para iniciantes

Se você está começando a explorar o mundo da Inteligencia Artifical (IA) e quer entender como utilizar a funcionalidade de retrieval dos assistants da OpenAI, você está no lugar certo! Neste post, vamos explicar o que é o retrieval, como ele funciona e como você pode utilizá-lo em suas aplicações de IA. Vamos lá!

O que é OpenAI Assistant Retrieval?

O OpenAI Assistant Retrieval é uma funcionalidade que permite aos modelos de IA acessarem informações de arquivos externos, como PDFs, documentos de texto ou planilhas para gerar respostas mais precisas e contextualizadas.

Em vez de depender apenas do conhecimento interno do modelo, o retrieval busca trechos relevantes nos documentos que você fornece, tornando as respostas baseadas em dados reais e atualizados.

Por que usar Retrieval OpenAI?

O OpenAI Retrieval resolve um problema comum em aplicações de IA: a falta de acesso a informações específicas e atualizadas. Com essa funcionalidade, você pode:

• Criar assistentes especializados em documentação corporativa;
• Analisar relatórios financeiros automaticamente;
• Desenvolver chatbots que respondem baseados em manuais técnicos;
• Implementar sistemas de suporte que citam políticas internas.

A API OpenAI Retrieval se integra perfeitamente com o Python, tornando a implementação simples mesmo para iniciantes.

Como funciona o Retrieval OpenAI?

O processo de retrieval IA OpenAI segue 4 etapas principais:

1. Carregamento do arquivo: você envia um documento (PDF, TXT, etc.) para a OpenAI usando a API;
2. Segmentação e indexação: o documento é dividido em partes menores e transformado em embeddings (representações vetoriais);
3. Busca vetorial (OpenAI File Search): quando você faz uma pergunta, o assistente busca os trechos mais relevantes usando similaridade vetorial;
4. Geração da resposta: o modelo usa os trechos encontrados para criar uma resposta contextualizada.

Essa abordagem combina busca semântica com geração de texto, garantindo respostas mais fundamentadas.

Diferença entre Retrieval e File Search na OpenAI

É importante entender que OpenAI File Search é a tecnologia de busca vetorial que alimenta o retrieval. Enquanto o file search localiza trechos relevantes no documento, o retrieval é o processo completo que inclui busca + geração de resposta contextualizada.

Na prática, quando você habilita tools=[{‘type’: ‘retrieval’}], está ativando todo esse fluxo automaticamente.

Tutorial prático: Retrieval Python OpenAI passo a passo

Vamos criar um assistente que analisa dados financeiros da Ambev usando um documento PDF real. Este OpenAI Assistant tutorial é ideal para quem está começando.

Pré-requisitos para usar Retrieval OpenAI

Antes de começar este tutorial retrieval OpenAI, você precisa:

• Python 3.8 ou superior instalado;
• Biblioteca OpenAI instalada: pip install openai python-dotenv;
• Uma API key da OpenAI configurada;
• Um documento PDF para testar (usaremos demonstrações financeiras da Ambev).

Passo 1: Carregar o arquivo na API OpenAI

Primeiro, envie o PDF para o servidor da OpenAI usando a API OpenAI Retrieval:

from openai import OpenAI
from dotenv import load_dotenv, find_dotenv

load_dotenv(find_dotenv())
client = OpenAI()

# Enviar arquivo para a OpenAI
file = client.files.create(
    file=open('arquivos/divulgacao_resultado_ambev_4T23.pdf', 'rb'),
    purpose='assistants'
)

print(f"Arquivo enviado com ID: {file.id}")

from openai import OpenAI
from dotenv import load_dotenv, find_dotenv

load_dotenv(find_dotenv())
client = OpenAI()

# Enviar arquivo para a OpenAI
file = client.files.create(
    file=open('arquivos/divulgacao_resultado_ambev_4T23.pdf', 'rb'),
    purpose='assistants'
)

print(f"Arquivo enviado com ID: {file.id}")

Passo 2: Criar o Assistant com Retrieval habilitado

Configure o assistente e ative a ferramenta de retrieval OpenAI:

# Criar assistant com retrieval habilitado
assistant = client.beta.assistants.create(
    name="Analista de Demonstrações Financeiras",
    instructions="Você é um analista da Ambev. Use apenas o documento fornecido para responder perguntas sobre resultados financeiros.",
    tools=[{'type': 'retrieval'}],  # Habilita OpenAI Assistant Retrieval
    file_ids=[file.id],
    model='gpt-4o-mini'
)

print(f"Assistant criado com ID: {assistant.id}")

# Criar assistant com retrieval habilitado
assistant = client.beta.assistants.create(
    name="Analista de Demonstrações Financeiras",
    instructions="Você é um analista da Ambev. Use apenas o documento fornecido para responder perguntas sobre resultados financeiros.",
    tools=[{'type': 'retrieval'}],  # Habilita OpenAI Assistant Retrieval
    file_ids=[file.id],
    model='gpt-4o-mini'
)

print(f"Assistant criado com ID: {assistant.id}")

Passo 3: Como usar Retrieval OpenAI para fazer perguntas

Crie uma thread e envie sua pergunta usando retrieval Python OpenAI:

# Criar thread
thread = client.beta.threads.create()

# Enviar pergunta
pergunta = 'Qual o volume de cerveja vendido no Brasil segundo o documento?'

message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role='user',
    content=pergunta
)

# Executar o assistant com retrieval
run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id
)

# Criar thread
thread = client.beta.threads.create()

# Enviar pergunta
pergunta = 'Qual o volume de cerveja vendido no Brasil segundo o documento?'

message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role='user',
    content=pergunta
)

# Executar o assistant com retrieval
run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id
)

Passo 4: Aguardar e verificar a resposta do Retrieval

Aguarde o processamento e recupere a resposta:

import time

# Aguardar conclusão do retrieval
while run.status in ['queued', 'in_progress', 'cancelling']:
    time.sleep(1)
    run = client.beta.threads.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id
    )

# Recuperar resposta gerada pelo retrieval
messages = client.beta.threads.messages.list(thread_id=thread.id)
resposta = messages.data[-1].content[0].text.value
print(resposta)
```

**Exemplo de resposta do OpenAI Assistant Retrieval:**
```
Segundo o documento, o volume de cerveja vendido no Brasil pela Ambev em 2023 foi de 183.659 mil hectolitros, uma redução de 11% em relação a 2022 (185.749 mil hectolitros).

import time

# Aguardar conclusão do retrieval
while run.status in ['queued', 'in_progress', 'cancelling']:
    time.sleep(1)
    run = client.beta.threads.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id
    )

# Recuperar resposta gerada pelo retrieval
messages = client.beta.threads.messages.list(thread_id=thread.id)
resposta = messages.data[-1].content[0].text.value
print(resposta)
```

**Exemplo de resposta do OpenAI Assistant Retrieval:**
```
Segundo o documento, o volume de cerveja vendido no Brasil pela Ambev em 2023 foi de 183.659 mil hectolitros, uma redução de 11% em relação a 2022 (185.749 mil hectolitros).

Casos de uso avançados do OpenAI Retrieval

Agora que você aprendeu como usar retrieval OpenAI, veja aplicações práticas:

1. Análise de múltiplos documentos

Você pode enviar vários arquivos e o retrieval IA OpenAI buscará informações em todos eles:

# Enviar múltiplos arquivos
file_ids = []
documentos = ['relatorio_2022.pdf', 'relatorio_2023.pdf', 'relatorio_2024.pdf']

for doc in documentos:
    file = client.files.create(
        file=open(f'arquivos/{doc}', 'rb'),
        purpose='assistants'
    )
    file_ids.append(file.id)

# Criar assistant com todos os arquivos
assistant = client.beta.assistants.create(
    name="Analista Comparativo",
    instructions="Compare dados entre os anos usando os documentos fornecidos.",
    tools=[{'type': 'retrieval'}],
    file_ids=file_ids,
    model='gpt-4o-mini'
)

# Enviar múltiplos arquivos
file_ids = []
documentos = ['relatorio_2022.pdf', 'relatorio_2023.pdf', 'relatorio_2024.pdf']

for doc in documentos:
    file = client.files.create(
        file=open(f'arquivos/{doc}', 'rb'),
        purpose='assistants'
    )
    file_ids.append(file.id)

# Criar assistant com todos os arquivos
assistant = client.beta.assistants.create(
    name="Analista Comparativo",
    instructions="Compare dados entre os anos usando os documentos fornecidos.",
    tools=[{'type': 'retrieval'}],
    file_ids=file_ids,
    model='gpt-4o-mini'
)

2. Citação de fontes com OpenAI File Search

Configure o assistant para sempre citar as fontes:

assistant = client.beta.assistants.create(
    name="Assistente com Citações",
    instructions="Responda usando apenas o documento. Sempre cite a página ou seção de onde extraiu a informação.",
    tools=[{'type': 'retrieval'}],
    file_ids=[file.id],
    model='gpt-4o-mini'
)

assistant = client.beta.assistants.create(
    name="Assistente com Citações",
    instructions="Responda usando apenas o documento. Sempre cite a página ou seção de onde extraiu a informação.",
    tools=[{'type': 'retrieval'}],
    file_ids=[file.id],
    model='gpt-4o-mini'
)

3. Filtragem de informações específicas

Use instruções detalhadas para guiar o retrieval OpenAI:

pergunta = """
Com base no documento, liste APENAS:
1. Receita líquida do 4º trimestre
2. EBITDA ajustado
3. Volume total de vendas

Formate como JSON.
"""

pergunta = """
Com base no documento, liste APENAS:
1. Receita líquida do 4º trimestre
2. EBITDA ajustado
3. Volume total de vendas

Formate como JSON.
"""

Quando usar OpenAI Assistant Retrieval?

O retrieval OpenAI é ideal para:

• Análise de documentos corporativos (relatórios, contratos, políticas);
• Suporte ao cliente baseado em manuais técnicos;
• Pesquisa acadêmica com papers e artigos;
• Assistentes jurídicos ou financeiros que precisam citar fontes;
• Chatbots especializados em documentação interna;
• Sistemas de Q&A sobre bases de conhecimento.

Domine a criação de Agentes de IA com Agno

Na Formação Engenheiro de Agentes de IA, você vai além do OpenAI Assistant Retrieval e aprende a criar agentes autônomos completos com:

• Memória embutida e raciocínio estruturado;
• Integração nativa com APIs, bancos de dados e ferramentas externas;
• Mais de 80 ferramentas integradas e suporte a MCPs (Model-Context Protocols);
• Interface open-source para gerenciar e debugar agentes;
• Domínio completo de frameworks como Agno, LangChain e muito mais.

Comece do zero com lógica de programação e Python, depois avance para construir agentes que trabalham em equipe e resolvem problemas complexos de forma coordenada.

Inscreva-se na Formação Engenheiro de Agentes de IA 

Formação Engenheiro de Agentes de IA

Domine os frameworks de criação de agentes de IA mais avançados da atualidade e aprenda a transformar qualquer LLM em um agente!

Comece agora