API de Embeddings da OpenAI: Criar e Verificar a Pesquisa Semântica

Está procurando a API de embeddings da OpenAI? O endpoint de embeddings da OpenAI converte texto em vetores numéricos para que uma aplicação possa recuperar passagens relacionadas. A solicitação é apenas o primeiro passo: um recurso de pesquisa útil também precisa de IDs de documento estáveis, um espaço vetorial consistente e um teste que indique se a recuperação melhorou.

Este guia cria um pequeno exemplo de pesquisa em Python, mostra o que armazenar junto a cada vetor e fornece uma lista de verificação para levar o experimento a um produto. Ele usa a OpenAI diretamente. A compatibilidade de gateways e a disponibilidade de modelos devem ser verificadas separadamente para cada provedor.

API de embeddings da OpenAI: a solicitação de que você precisa

Envie texto para POST https://api.openai.com/v1/embeddings com um modelo de embedding e uma chave de API. Escolha encoding_format="float" quando sua aplicação esperar matrizes numéricas. Para um lote, use o index de cada item da resposta para reconectar o vetor à sua entrada. A resposta também inclui o uso de tokens. A opção dimensions é compatível com os modelos de embedding de terceira geração. Referência da API da OpenAI.

Um embedding não é uma resposta gerada. Em uma aplicação com geração aumentada por recuperação, a pesquisa primeiro seleciona passagens de origem; uma chamada de geração separada pode então responder usando essas passagens. Manter as etapas separadas permite diagnosticar um resultado ruim: a pesquisa recuperou a evidência errada ou o modelo de resposta usou mal uma boa evidência?

Escolha um modelo e mantenha sua configuração fixa

Os comprimentos de vetor padrão documentados são 1.536 para text-embedding-3-small e 3.072 para text-embedding-3-large. Esses modelos oferecem suporte a vetores de saída menores por meio de dimensions. Um vetor menor altera os compromissos entre armazenamento e recuperação; não é motivo para deixar de avaliar. Guia de embeddings da OpenAI.

Comece com uma configuração e um pequeno conjunto de consultas representativas. Registre o modelo, a contagem de dimensões solicitada e a versão de processamento de texto junto ao índice. Dois vetores com o mesmo comprimento não comprovam que vieram de um modelo compatível. Ao alterar modelos ou regras de processamento, crie um índice separado e compare-o antes de mudar o tráfego de produção.

Um exemplo mínimo de pesquisa semântica em Python

Instale openai em seu ambiente Python e disponibilize OPENAI_API_KEY por meio do seu gerenciador de segredos habitual ou da configuração de ambiente. Mantenha a chave fora do controle de versão e do código do navegador. O SDK oficial do Python lê essa variável ao construir OpenAI().

Salve o conteúdo a seguir como search_demo.py. Ele usa três documentos de suporte inventados, gera embeddings para o corpus e uma consulta, e classifica os documentos com similaridade de cosseno. Sua execução faz solicitações de API faturáveis. A saída depende da resposta do serviço; o exemplo não promete uma pontuação ou classificação específica.

import math
from openai import OpenAI

client = OpenAI(timeout=30.0, max_retries=2)
model = "text-embedding-3-small"
dimensions = 1536

documents = [
    {"id": "key-rotation", "text": "Replace an exposed API key and revoke the old credential."},
    {"id": "invoice-export", "text": "Download a monthly invoice from the billing workspace."},
    {"id": "request-timeout", "text": "Record the request ID and retry temporary upstream timeouts."},
]
query = "What should I do after accidentally sharing a secret key?"


def embed(texts):
    response = client.embeddings.create(
        model=model, input=texts,
        dimensions=dimensions, encoding_format="float",
    )
    ordered = sorted(response.data, key=lambda item: item.index)
    if [item.index for item in ordered] != list(range(len(texts))):
        raise ValueError("Unexpected embedding response indices")
    vectors = [item.embedding for item in ordered]
    if any(len(vector) != dimensions for vector in vectors):
        raise ValueError("Unexpected vector dimensions")
    print("Input tokens:", response.usage.prompt_tokens)
    return vectors


def cosine(a, b):
    if len(a) != len(b):
        raise ValueError("Vector dimensions do not match")
    denominator = math.sqrt(sum(x*x for x in a) * sum(y*y for y in b))
    if not denominator:
        raise ValueError("Cannot compare a zero vector")
    return sum(x*y for x, y in zip(a, b)) / denominator


vectors = embed([document["text"] for document in documents])
query_vector = embed([query])[0]
ranked = sorted(
    ((cosine(query_vector, vector), document["id"])
     for document, vector in zip(documents, vectors)),
    reverse=True,
)
for score, document_id in ranked:
    print(document_id, round(score, 4))

Execute python search_demo.py. Confirme que todos os três IDs aparecem uma vez e que cada embedding tem o comprimento configurado. Em seguida, altere a consulta para perguntar sobre faturas. Este é um teste rápido do fluxo de dados, não uma prova de que o sistema está pronto para tráfego real de suporte. O exemplo gera embeddings para o corpus novamente a cada execução para maior clareza; um serviço implantado normalmente deve persistir os vetores de documentos e gerar embeddings apenas para conteúdo novo ou alterado.

Transforme a demonstração em um índice de documentos confiável

O layout de registro a seguir é um ponto de partida prático. Ele é um exemplo de design de aplicação, não um esquema de campos exigido pela OpenAI.

Divida os documentos em limites significativos e, em seguida, verifique o comprimento em tokens. Uma seção que contenha a resposta à pergunta deve permanecer compreensível quando recuperada isoladamente. Avalie a sobreposição de forma deliberada: sobreposição excessiva pode preencher o conjunto de resultados com versões repetidas da mesma passagem.

Para o primeiro experimento, o loop em memória acima é suficiente. À medida que o corpus cresce, use um índice ou armazenamento de vetores que suporte o comportamento de filtragem, exclusão e recuperação necessário. Teste essas operações antes de confiar nas pontuações de similaridade. Uma passagem altamente semelhante do cliente errado jamais deve ser retornada apenas porque ficou em primeiro lugar.

Verifique separadamente os limites de entrada e de lote

A referência atual do endpoint da OpenAI especifica um máximo de 8.192 tokens por entrada e um máximo agregado de 300.000 tokens entre as entradas em uma solicitação; ela também documenta um máximo de 2.048 entradas por lote. Texto vazio é inválido. Conte tokens, e não caracteres, e deixe margem abaixo dos limites ao construir lotes. Restrições do endpoint.

Se você usa o Azure OpenAI, a configuração do endpoint, a autenticação e a nomenclatura da implantação têm sua própria configuração. Siga as instruções de embeddings do Azure para esse serviço, em vez de supor que uma solicitação direta à OpenAI pode ser copiada sem alterações. Aplique a mesma separação ao usar um gateway: primeiro verifique o endpoint, o acesso ao modelo, os parâmetros compatíveis e a conta de faturamento.

Estime o custo sem ocultar reconstruções de índice

O custo de embeddings acompanha os tokens de entrada; portanto, conte separadamente a ingestão de documentos, os fragmentos alterados e os embeddings de consulta. Use o preço atual na página do modelo relevante, como text-embedding-3-small, e confirme se a tarifa informada se aplica ao seu modo de solicitação.

Como exemplo de planejamento, seja P o preço verificado por milhão de tokens de entrada:

Ingestão inicial: 50.000 fragmentos × 400 tokens = 20 milhões de tokens
Alterações mensais: 5.000 fragmentos × 400 tokens =  2 milhões de tokens
Consultas mensais: 200.000 consultas × 20 tokens =  4 milhões de tokens

Custo inicial de embeddings = 20 × P
Custo recorrente de embeddings = (2 + 4) × P = 6 × P

Essas são suposições ilustrativas de carga de trabalho, não preços da Flatkey ou da OpenAI. Adicione separadamente o armazenamento de vetores, a infraestrutura de busca e quaisquer chamadas de geração de respostas. Se você mudar o modelo de embedding, inclua uma passagem completa de re-embedding no orçamento de migração. Um pipeline que gera embeddings novamente para documentos inalterados pode gastar mais do que a mesma carga de trabalho com um modelo maior, mas armazenado corretamente em cache.

Diagnostique erros antes de adicionar tentativas

As quatro primeiras verificações seguem o guia de erros da OpenAI. As duas últimas dizem respeito ao seu aplicativo e índice. Respeite as orientações de repetição do servidor e considere as repetições do SDK antes de adicionar outro loop de repetição. Registre metadados operacionais sem registrar credenciais ou texto privado desnecessário de documentos.

Avalie a recuperação antes de escolher um modelo de resposta

Crie um pequeno conjunto rotulado com perguntas reais de usuários, incluindo paráfrases, nomes exatos de produtos, perguntas ambíguas e perguntas que seu corpus não pode responder. Anote o documento de origem esperado para cada consulta respondível antes de ajustar o sistema.

Para cada configuração candidata, registre se uma fonte aceitável aparece nos primeiros resultados, quanto material duplicado é retornado, a latência de recuperação e o custo por consulta. Revise as falhas individualmente. Se uma consulta pede um código de erro exato, uma correspondência por palavra-chave pode complementar a similaridade semântica. Se a fonte estiver ausente, alterar as dimensões dos embeddings não pode inventá-la.

Mantenha uma parte das perguntas separada para a comparação final. Não escolha um limiar de similaridade com base na demonstração de três documentos e o trate como uma pontuação universal de confiança. Um teste de aceitação útil reflete as consequências da recuperação incorreta em seu próprio aplicativo.

Onde a Flatkey se encaixa no aplicativo

A Flatkey fornece um roteador de modelos compatível com a OpenAI e um diretório de modelos atual. Use a documentação de integração da Flatkey para avaliar o lado de geração de modelos da sua aplicação. Os exemplos acima chamam a OpenAI diretamente; eles não estabelecem que um modelo de embeddings ou todos os parâmetros de embeddings estejam disponíveis por meio da Flatkey.

Para uma aplicação com vários provedores, mantenha a configuração de recuperação independente da configuração do modelo de resposta. Isso permite comparar modelos de resposta sem reconstruir o índice de documentos para cada experimento. Consulte os guias de arquitetura de API da Flatkey ao planejar roteamento, controles de conta e verificações operacionais.

Perguntas frequentes

A API de embeddings responde a perguntas por si só?

Ela retorna vetores. Sua aplicação os utiliza para selecionar conteúdo relacionado; um modelo de resposta é um componente separado se você precisar de uma resposta escrita.

Posso comparar vetores de diferentes modelos de embeddings?

Não presuma que eles compartilham um espaço de coordenadas significativo, mesmo que suas dimensões correspondam. Mantenha índices específicos do modelo e avalie migrações usando as mesmas perguntas e documentos de origem.

Devo escolher imediatamente o maior modelo de embeddings?

Comece com uma configuração que você possa medir. Compare a qualidade da recuperação, a latência, o armazenamento e o custo em suas próprias consultas antes de adotar um índice maior ou um modelo diferente.

O que devo criar primeiro?

Use a API de embeddings da Open AI para incorporar um pequeno corpus seguro em relação a permissões, verificar o mapeamento de documento para vetor e testar a recuperação com perguntas rotuladas. Expanda o corpus depois que esse ciclo produzir evidências confiáveis.