Um guia completo para a API de Arquivos da OpenAI

Então, quer colocar os seus próprios documentos nos modelos da OpenAI. É um objetivo bastante comum: quer construir um bot de apoio ao cliente que realmente conheça os seus documentos de ajuda, ou afinar um modelo com os dados privados da sua empresa. A API de Ficheiros da OpenAI é o seu bilhete para o conseguir.

Mas há um senão: trabalhar diretamente com a API pode dar a sensação de que está a construir imensa canalização só para fazer a água correr. É um processo com muito código, muitos passos, espera pelo processamento e uma gestão de ficheiros algo complicada.

Este guia irá acompanhá-lo por todo o processo, desde as chamadas básicas da API até às dores de cabeça comuns que os programadores enfrentam. Vamos abordar como carregar, gerir e usar ficheiros da forma tradicional (DIY) e, depois, explorar um caminho muito mais simples para empresas que apenas querem o trabalho feito.

O que é a API de Ficheiros da OpenAI?

A API de Ficheiros da OpenAI é um conjunto de ferramentas que lhe permite carregar, gerir e apagar ficheiros nos servidores da OpenAI. Pense nela como um disco na nuvem específico para os documentos que pretende que as suas aplicações de IA utilizem.

Quando carrega um ficheiro, tem de lhe atribuir um "propósito", que é apenas uma forma de dizer à OpenAI como planeia usá-lo. Os principais propósitos que encontrará são:

• "assistants": Serve para fornecer documentos à API de Assistentes. É frequentemente utilizada com a ferramenta "file_search" (anteriormente chamada de recuperação), permitindo a um assistente consultar informações nos seus ficheiros para responder a perguntas.

• "fine-tune": Utilizará este propósito quando estiver a fornecer dados de treino para criar um modelo personalizado e afinado.

• "vision": Como deve adivinhar, serve para carregar imagens para que modelos como o GPT-4o as analisem.

• "batch": Serve para fornecer ficheiros de entrada à API de Lote (Batch API), que é útil para executar grandes tarefas sem ter de esperar por elas em tempo real.

Basicamente, a API de Ficheiros é o primeiro passo para construir uma IA que sabe mais do que apenas o que aprendeu na internet pública.

Como usar a API de Ficheiros da OpenAI (da forma intensiva para programadores)

Utilizar diretamente a API dá-lhe controlo total, mas também significa que é responsável por escrever o código para gerir tudo. Vamos analisar como isto funciona em alguns cenários comuns.

Carregar e gerir ficheiros de forma programática

O núcleo da API resume-se a alguns comandos principais. Antes de começar, vai precisar do SDK da OpenAI para a sua linguagem de eleição. Para Python, basta um rápido "pip install openai".

Vamos então pôr as mãos na massa com algum código. Eis como é o fluxo de trabalho básico:

1. Carregar um ficheiro: Primeiro, abre um ficheiro do seu computador e carrega-o, indicando à OpenAI qual é o seu propósito.

    from openai import OpenAI  

    client = OpenAI()  

    # Upload a file with an "assistants" purpose  

    file = client.files.create(  

      file=open("my-knowledge-base.pdf", "rb"),  

      purpose="assistants"  

    )  

    print(file.id)  

2. Listar os seus ficheiros: Precisa de ver tudo o que carregou? Pode obter uma lista de todos os ficheiros na sua organização.

    all_files = client.files.list()  

    print(all_files)  

3. Verificar um ficheiro: Depois de carregar um ficheiro, pode verificar os seus metadados para ver o seu estado, que será "uploaded", "processed" ou "error".

    file_info = client.files.retrieve("YOUR_FILE_ID")  

    print(file_info.status)  

4. Apagar um ficheiro: Se já não precisar de um ficheiro, pode removê-lo para limpar o seu armazenamento.

    client.files.delete("YOUR_FILE_ID")  

Estes passos parecem bastante simples para um ou dois ficheiros. Mas e se tiver centenas? Ou milhares? A API não tem operações em massa, por isso teria de construir os seus próprios scripts para percorrer cada ficheiro individualmente. É aqui que a abordagem liderada pelo programador começa a parecer uma verdadeira tarefa árdua.

Usar a API com assistentes e pesquisa de ficheiros

Prepare-se, porque a próxima parte é uma dança com vários passos. Se quiser que um Assistente utilize realmente um dos seus ficheiros carregados para responder a perguntas, tem de trabalhar com algo chamado Vector Stores. Um Vector Store é basicamente uma coleção processada e indexada dos seus ficheiros, otimizada para pesquisas rápidas.

Eis o fluxo de trabalho típico que teria de construir de raiz:

1. Carregue o(s) seu(s) ficheiro(s) com a API de Ficheiros.

2. Crie um Vector Store.

3. Adicione o(s) seu(s) ficheiro(s) carregado(s) a esse novo Vector Store.

4. Espere. E continue a verificar (ou a fazer "polling") o estado do ficheiro até estar totalmente processado.

5. Crie um Assistente e certifique-se de que ativa a ferramenta "file_search".

6. Anexe o seu Vector Store ao Assistente.

7. Crie uma Thread para iniciar uma conversa.

8. Adicione a pergunta do utilizador à Thread.

9. Crie uma "Run" para que o Assistente processe a pergunta.

10. Faça "polling" do estado da Run até que finalmente apareça como "completed".

11. E, finalmente, pode obter a resposta do Assistente a partir da Thread.

Reparou em todo o "polling"? Depois de adicionar um ficheiro a um Vector Store, não o pode usar imediatamente. A sua aplicação tem de continuar a perguntar à API: "Já está pronto?". Isto adiciona uma camada de complexidade e significa que tem de construir um tratamento de erros e gestão de estado robustos apenas para que funcione de forma fiável.

Para equipas que não têm engenheiros de IA dedicados, construir e manter todo este sistema é um grande desafio. É uma queixa comum em comunidades de programadores, onde as pessoas ficam frequentemente surpreendidas com a quantidade de trabalho necessária para fazer algo que parece simples: "responder a perguntas com base nos meus documentos".

Preços e limitações da API de Ficheiros da OpenAI

Antes de mergulhar e começar a construir, é boa ideia saber no que se está a meter em termos de custos e limitações.

Quanto custa usar a API de Ficheiros da OpenAI?

Quando utiliza a API de Ficheiros, não paga apenas pelos tokens do modelo. Também é cobrado pelo armazenamento que os seus ficheiros ocupam.

• Custo de Armazenamento: A OpenAI cobra pelo armazenamento dos seus ficheiros e das suas versões indexadas em Vector Stores. A taxa atual é de $0,10 por GB por dia, embora o primeiro 1 GB seja gratuito.

• Custos de Tokens: Quando um assistente utiliza a "file_search" para encontrar uma resposta, os trechos relevantes do seu documento são inseridos na janela de contexto do modelo. Isto consome tokens de prompt, pelos quais é cobrado.

Este preço em duas partes pode tornar difícil prever a sua fatura mensal, uma vez que depende da quantidade de dados que armazena e da frequência com que o seu assistente os utiliza.

Desafios e limitações comuns

A API em bruto é poderosa, mas tem algumas peculiaridades que o podem atrasar.

• Não pode fazer coisas em massa: A API não suporta o carregamento ou a eliminação de múltiplos ficheiros de uma só vez. Tem de escrever um script para os percorrer um a um, o que pode ser dolorosamente lento.

• Não há interface visual: Não pode simplesmente iniciar sessão num dashboard para ver todos os seus ficheiros carregados, verificar o seu estado ou descobrir que assistentes os estão a utilizar. Isto torna a gestão e a depuração uma verdadeira dor de cabeça.

• Tem de esperar... e verificar... e esperar mais um pouco: Como mencionámos, o processamento de ficheiros é assíncrono. O seu código tem de verificar constantemente com a API se um ficheiro está pronto, o que complica a sua lógica e pode introduzir atrasos.

• A gestão de conhecimento torna-se confusa: Ligar ficheiros específicos a assistentes específicos envolve fazer malabarismos com IDs de "Vector Store" e objetos "tool_resources". Não há uma forma fácil de simplesmente dizer: "Ei, responde a esta pergunta usando apenas estes três documentos", sem uma codificação cuidadosa.

Estas limitações significam frequentemente que um projeto que parece simples à primeira vista pode transformar-se num grande esforço de engenharia. Acaba por gastar mais tempo a construir ferramentas básicas de gestão de ficheiros do que na sua aplicação real.

A forma mais fácil: Gerir o seu conhecimento com uma plataforma integrada

Construir tudo por conta própria na API de Ficheiros da OpenAI dá-lhe flexibilidade, mas é uma enorme perda de tempo. Para a maioria das empresas, especialmente as de apoio ao cliente ou TI, uma plataforma pronta a usar que esconde toda essa complexidade é uma solução muito melhor.

É aqui que entra uma solução como a eesel AI. Foi construída para ligar o conhecimento existente da sua empresa a um agente de IA, sem que tenha de escrever uma única linha de código de API.

Entre em funcionamento em minutos com integrações de um clique

Em vez de lutar com scripts para carregar ficheiros um a um, a eesel AI tem integrações simples para as ferramentas que já utiliza. Pode ligar o seu help desk (como o Zendesk ou o Freshdesk), a sua base de conhecimento (como o Confluence ou o Notion) e os seus documentos partilhados (como o Google Docs) com apenas alguns cliques. A eesel AI trata de toda a sincronização, processamento e indexação de ficheiros nos bastidores.

Uma captura de ecrã da plataforma eesel AI a mostrar várias integrações de um clique, simplificando a forma como as empresas ligam o seu conhecimento a um chatbot da OpenAI sem usar diretamente a API de Ficheiros da OpenAI.

Unifique todo o seu conhecimento sem trabalho manual

A API de Ficheiros da OpenAI obriga-o a carregar e organizar cada documento. Com a eesel AI, o seu conhecimento é unificado desde o início. Pode até aprender com os tickets de suporte passados da sua equipa para captar a voz da sua marca e os problemas comuns dos clientes. Isso significa que o seu agente de IA é treinado no contexto específico do seu negócio desde o primeiro dia, sem que tenha de preparar e carregar manualmente milhares de ficheiros.

Teste com confiança antes de lançar

Uma das partes mais assustadoras de construir sobre a API em bruto é não saber como a sua IA se irá realmente comportar com perguntas reais. O modo de simulação da eesel AI trata disso, testando o seu agente de IA em milhares dos seus tickets de suporte históricos. Pode ver como teria respondido e obter previsões sólidas sobre quantos tickets consegue resolver e quanto dinheiro irá poupar. Pode até começar por automatizar apenas uma categoria de tickets e expandir a partir daí, mantendo-o em controlo total.

Considerações finais

A API de Ficheiros da OpenAI é uma peça fundamental do quebra-cabeças para criar uma IA que compreende os seus dados únicos. Para programadores que precisam de construir algo completamente personalizado, oferece todo o poder e controlo que poderiam desejar.

Mas para a maioria das empresas, o objetivo não é tornarem-se especialistas em orquestração de APIs. É resolver um problema, como libertar a sua equipa de suporte de perguntas repetitivas. A complexidade de gerir ficheiros, fazer polling de estados e a falta de uma interface de utilizador tornam a API direta um caminho difícil para esse fim.

Plataformas como a eesel AI tratam de toda essa confusão por si, oferecendo uma forma extremamente simples e self-service de ligar o seu conhecimento e automatizar o suporte. Em vez de passar meses a construir infraestrutura, pode ter uma solução a funcionar em minutos e focar-se no que realmente importa: deixar os seus clientes felizes.

Pronto para pôr o conhecimento da sua empresa a trabalhar sem a dor de cabeça da engenharia? Comece a usar a eesel AI gratuitamente.