--- title: Embeddings url: https://platform.claude.com/docs/pt-BR/build-with-claude/embeddings description: Embeddings de texto são representações numéricas de texto que permitem medir a similaridade semântica. Este guia apresenta os embeddings, suas aplicações e como usar modelos de embedding para tarefas como busca, recomendações e detecção de anomalias. --- ## Antes de implementar embeddings Ao selecionar um provedor de embeddings, há vários fatores que você pode considerar dependendo de suas necessidades e preferências: * Tamanho do conjunto de dados e especificidade de domínio: tamanho do conjunto de dados de treinamento do modelo e sua relevância para o domínio que você deseja incorporar. Dados maiores ou mais específicos do domínio geralmente produzem melhores embeddings dentro do domínio * Desempenho de inferência: velocidade de consulta de embeddings e "latency" (latência) de ponta a ponta. Esta é uma consideração particularmente importante para implantações de produção em larga escala * Personalização: opções para treinamento contínuo em dados privados ou especialização de modelos para domínios muito específicos. Isso pode melhorar o desempenho em vocabulários únicos ## Como obter embeddings com a Anthropic A Anthropic não oferece seu próprio modelo de embedding. Um provedor de embeddings com uma ampla variedade de modelos e recursos é a Voyage AI by MongoDB. A Voyage AI cria modelos de embedding e "rerankers" (reclassificadores). Seus modelos de embedding incluem modelos de uso geral, multimodais, contextualizados e específicos de domínio. O restante deste guia é para a Voyage AI, mas você deve avaliar uma variedade de fornecedores de embeddings para encontrar o mais adequado ao seu caso de uso específico. ## Modelos disponíveis A Voyage AI oferece os seguintes modelos de embedding de texto: **Geração mais recente** | Modelo | Comprimento de contexto | Dimensão do embedding | Descrição | | ---------------- | ----------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `voyage-4-large` | 32.000 | 1024 (padrão), 256, 512, 2048 | A melhor qualidade de recuperação de uso geral e multilíngue. Consulte a [postagem do blog sobre o Voyage 4](https://blog.voyageai.com/2026/01/15/voyage-4/) para detalhes. | | `voyage-4` | 32.000 | 1024 (padrão), 256, 512, 2048 | Otimizado para qualidade de recuperação de uso geral e multilíngue. Equilibra qualidade e eficiência. Consulte a [postagem do blog sobre o Voyage 4](https://blog.voyageai.com/2026/01/15/voyage-4/) para detalhes. | | `voyage-4-lite` | 32.000 | 1024 (padrão), 256, 512, 2048 | Otimizado para latência e custo. Consulte a [postagem do blog sobre o Voyage 4](https://blog.voyageai.com/2026/01/15/voyage-4/) para detalhes. | | `voyage-code-4` | 32.000 | 1024 (padrão), 256, 512, 2048 | Otimizado para recuperação de **código** e aplicações de codificação agêntica. Consulte a [postagem do blog sobre o voyage-code-4](https://blog.voyageai.com/2026/08/13/voyage-code-4/) para mais detalhes. | | `voyage-4-nano` | 32.000 | 2048 (padrão), 256, 512, 1024 | Modelo de pesos abertos (licença Apache 2.0) que você baixa do [Hugging Face](https://huggingface.co/voyageai/voyage-4-nano) e executa por conta própria. Não disponível por meio da Atlas Embedding and Reranking API. Consulte a [postagem do blog sobre o Voyage 4](https://blog.voyageai.com/2026/01/15/voyage-4/) para mais detalhes. | **Geração anterior** Para o status do ciclo de vida de cada modelo e a substituição recomendada, consulte [Model deprecations, lifecycle states, and support](https://www.mongodb.com/docs/voyageai/models/lifecycle/) na documentação do MongoDB. | Modelo | Comprimento de contexto | Dimensão do embedding | Descrição | | ------------------ | ----------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `voyage-3-large` | 32.000 | 1024 (padrão), 256, 512, 2048 | Geração anterior do `voyage-4-large`. Consulte a [postagem do blog sobre o voyage-3-large](https://blog.voyageai.com/2025/01/07/voyage-3-large/) para mais detalhes. | | `voyage-3.5` | 32.000 | 1024 (padrão), 256, 512, 2048 | Geração anterior do `voyage-4`. Consulte a [postagem do blog sobre o voyage-3.5](https://blog.voyageai.com/2025/05/20/voyage-3-5/) para mais detalhes. | | `voyage-3.5-lite` | 32.000 | 1024 (padrão), 256, 512, 2048 | Geração anterior do `voyage-4-lite`. Consulte a [postagem do blog sobre o voyage-3.5](https://blog.voyageai.com/2025/05/20/voyage-3-5/) para mais detalhes. | | `voyage-code-3` | 32.000 | 1024 (padrão), 256, 512, 2048 | Geração anterior do `voyage-code-4`. Consulte a [postagem do blog sobre o voyage-code-3](https://blog.voyageai.com/2024/12/04/voyage-code-3/) para mais detalhes. | | `voyage-finance-2` | 32.000 | 1024 | Otimizado para recuperação e RAG na área de **finanças**. Consulte a [postagem do blog sobre o voyage-finance-2](https://blog.voyageai.com/2024/06/03/domain-specific-embeddings-finance-edition-voyage-finance-2/) para mais detalhes. | | `voyage-law-2` | 16.000 | 1024 | Otimizado para recuperação e RAG na área **jurídica**. Consulte a [postagem do blog sobre o voyage-law-2](https://blog.voyageai.com/2024/04/15/domain-specific-embeddings-and-retrieval-legal-edition-voyage-law-2/) para mais detalhes. | Além disso, a Voyage AI oferece os seguintes modelos de embedding multimodais. Chame esses modelos com `multimodal_embed()` em vez de `embed()`: | Modelo | Comprimento de contexto | Dimensão do embedding | Descrição | | ----------------------- | ----------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `voyage-multimodal-3.5` | 32.000 | 1024 (padrão), 256, 512, 2048 | Modelo de embedding multimodal avançado que pode vetorizar texto, imagens e vídeos intercalados. Inclui suporte a vídeo como o primeiro modelo de embedding de vídeo de nível de produção. Consulte a [postagem do blog sobre o voyage-multimodal-3.5](https://blog.voyageai.com/2026/01/15/voyage-multimodal-3-5/) para mais detalhes. | | `voyage-multimodal-3` | 32.000 | 1024 | Geração anterior do `voyage-multimodal-3.5`. Vetoriza texto intercalado e imagens ricas em conteúdo, como capturas de tela de PDFs, slides, tabelas, figuras e muito mais. Consulte a [postagem do blog sobre o voyage-multimodal-3](https://blog.voyageai.com/2024/11/12/voyage-multimodal-3/) para mais detalhes. | Os seguintes modelos de embedding de chunks contextualizados produzem vetores em nível de chunk que capturam o contexto completo do documento sem aumento manual de metadados. Chame esses modelos com `contextualized_embed()` em vez de `embed()`: | Modelo | Comprimento de contexto | Dimensão do embedding | Descrição | | ------------------ | ----------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `voyage-context-4` | 120.000 | 1024 (padrão), 256, 512, 2048 | Embeddings de chunks contextualizados otimizados para qualidade de recuperação de uso geral e multilíngue. Consulte a [postagem do blog sobre o voyage-context-4](https://blog.voyageai.com/2026/06/29/voyage-context-4/) para mais detalhes. | | `voyage-context-3` | 120.000 | 1024 (padrão), 256, 512, 2048 | Geração anterior do `voyage-context-4`. Consulte a [postagem do blog sobre o voyage-context-3](https://blog.voyageai.com/2025/07/23/voyage-context-3/) para mais detalhes. | O limite de 120.000 tokens se aplica quando você define `enable_auto_chunking` como `true`. Caso contrário, o número total de tokens em todas as entradas não pode exceder 32.000. A Voyage AI também oferece rerankers, que recebem uma consulta e uma lista de documentos e os retornam classificados por relevância em relação à consulta. Chame esses modelos com `rerank()`: | Modelo | Comprimento de contexto | Descrição | | ----------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rerank-3` | 32.000 | Maior precisão. Recomendado para a maioria das aplicações. Consulte a [postagem do blog sobre o rerank-3](https://blog.voyageai.com/2026/09/30/rerank-3/) para mais detalhes. | | `rerank-3-lite` | 32.000 | Otimizado para latência e custo. Consulte a [postagem do blog sobre o rerank-3](https://blog.voyageai.com/2026/09/30/rerank-3/) para mais detalhes. | | `rerank-2.5` | 32.000 | Geração anterior do `rerank-3`. Consulte a [postagem do blog sobre o rerank-2.5](https://blog.voyageai.com/2025/08/11/rerank-2-5/) para mais detalhes. | | `rerank-2.5-lite` | 32.000 | Geração anterior do `rerank-3-lite`. Consulte a [postagem do blog sobre o rerank-2.5](https://blog.voyageai.com/2025/08/11/rerank-2-5/) para mais detalhes. | Precisa de ajuda para decidir qual modelo usar? Consulte [Voyage AI embedding and reranking models overview](https://www.mongodb.com/docs/voyageai/models/) na documentação do MongoDB. ## Primeiros passos com a Voyage AI Para acessar os modelos da Voyage AI, crie uma chave de API de modelo no MongoDB Atlas: 1. Crie uma conta do MongoDB Atlas ou faça login. 2. No seu projeto do Atlas, selecione **AI Model APIs** na barra de navegação, clique em **Create model API key**, dê um nome à chave e clique em **Create**. 3. Defina a chave de API como uma variável de ambiente por conveniência: ```bash export VOYAGE_API_KEY="" ``` Para mais detalhes, consulte [Voyage AI quick start](https://www.mongodb.com/docs/voyageai/quickstart/) na documentação do MongoDB. Você pode obter os embeddings usando o [pacote Python oficial `voyageai`](https://github.com/voyage-ai/voyageai-python) ou requisições HTTP, conforme descrito nas seções a seguir. A Voyage AI também tem um cliente TypeScript oficial. Para usá-lo com uma chave de API de modelo do Atlas, defina sua opção `environment` como `https://ai.mongodb.com/v1`, conforme descrito em [TypeScript client](https://www.mongodb.com/docs/voyageai/api-and-clients/#typescript-client) na documentação do MongoDB. ### Biblioteca Python da Voyage AI Instale o pacote `voyageai` usando o comando a seguir. Para usar uma chave de API de modelo do Atlas, você precisa da versão 0.3.7 ou posterior. ```bash pip install -U voyageai ``` Em seguida, você pode criar um objeto cliente e começar a usá-lo para gerar embeddings dos seus textos: ```python import voyageai vo = voyageai.Client() # Isso usará automaticamente a variável de ambiente VOYAGE_API_KEY. # Como alternativa, você pode usar vo = voyageai.Client(api_key="") texts = ["Sample text 1", "Sample text 2"] result = vo.embed(texts, model="voyage-4", input_type="document") print(result.embeddings[0]) print(result.embeddings[1]) ``` `result.embeddings` é uma lista de dois vetores de embedding, cada um contendo 1024 números de ponto flutuante. Após executar o código anterior, os dois embeddings são impressos na tela: ```text [-0.013131560757756233, 0.019828535616397858, ...] # embedding for "Sample text 1" [-0.0069352793507277966, 0.020878976210951805, ...] # embedding for "Sample text 2" ``` Ao criar os embeddings, você pode especificar alguns outros argumentos para a função `embed()`. Para mais informações sobre o pacote Python, consulte [Accessing Voyage AI models](https://www.mongodb.com/docs/voyageai/api-and-clients/) na documentação do MongoDB. ### API HTTP da Voyage AI Você também pode obter embeddings enviando requisições HTTP para a Atlas Embedding and Reranking API. Por exemplo, você pode enviar uma requisição HTTP por meio do comando `curl` em um terminal: ```bash cURL curl https://ai.mongodb.com/v1/embeddings \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $VOYAGE_API_KEY" \ -d '{ "input": ["Sample text 1", "Sample text 2"], "model": "voyage-4", "input_type": "document" }' ``` A resposta que você receberia é um objeto JSON contendo os embeddings e o uso de tokens: ```json { "object": "list", "data": [ { "object": "embedding", "embedding": [-0.013131560757756233, 0.019828535616397858 /* ... */], "index": 0 }, { "object": "embedding", "embedding": [-0.0069352793507277966, 0.020878976210951805 /* ... */], "index": 1 } ], "model": "voyage-4", "usage": { "total_tokens": 10 } } ``` As chaves de API de modelo do Atlas funcionam com `ai.mongodb.com`, exceto as chaves com escopo para uma região geográfica, que usam o endpoint dessa região. Se, em vez disso, você tiver uma chave de API da plataforma Voyage AI, consulte [Migrate your applications to use the Atlas Embedding and Reranking API](https://www.mongodb.com/docs/voyageai/tutorials/migrate-to-atlas/) na documentação do MongoDB. Para a referência completa de requisição e resposta, consulte [Create text embeddings](https://www.mongodb.com/docs/api/doc/atlas-embedding-and-reranking-api/operation/operation-createembedding) na documentação da Atlas Embedding and Reranking API. ### AWS Marketplace Os modelos da Voyage AI também estão disponíveis no AWS Marketplace por meio do [perfil de vendedor do MongoDB](https://aws.amazon.com/marketplace/seller-profile?id=c9032c7b-70dd-459f-834f-c1e23cf3d092). Para instruções, consulte [Deploy Voyage AI models using AWS Marketplace](https://www.mongodb.com/docs/voyageai/management/aws-marketplace/) na documentação do MongoDB. ## Exemplo de início rápido O breve exemplo a seguir mostra como usar embeddings. Suponha que você tenha um pequeno corpus de seis documentos dos quais recuperar ```python documents = [ "The Mediterranean diet emphasizes fish, olive oil, and vegetables, believed to reduce chronic diseases.", "Photosynthesis in plants converts light energy into glucose and produces essential oxygen.", "20th-century innovations, from radios to smartphones, centered on electronic advancements.", "Rivers provide water, irrigation, and habitat for aquatic species, vital for ecosystems.", "Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET.", "Shakespeare's works, like 'Hamlet' and 'A Midsummer Night's Dream,' endure in literature.", ] ``` Primeiro, use a Voyage AI para converter cada documento em um vetor de embedding. ```python import voyageai vo = voyageai.Client() # Gerar embeddings dos documentos doc_embds = vo.embed(documents, model="voyage-4", input_type="document").embeddings ``` Os embeddings permitem que você faça busca / recuperação semântica no espaço vetorial. Dada uma consulta de exemplo, ```python query = "When is Apple's conference call scheduled?" ``` Em seguida, converta-a em um embedding e realize uma busca de vizinho mais próximo para encontrar o documento mais relevante com base na distância no espaço de embeddings. ```python import numpy as np # Gera o embedding da consulta query_embd = vo.embed([query], model="voyage-4", input_type="query").embeddings[0] # Calcula a similaridade # Os embeddings da Voyage AI são normalizados para comprimento 1, então o produto escalar # e a similaridade de cosseno são iguais. similarities = np.dot(doc_embds, query_embd) retrieved_id = np.argmax(similarities) print(documents[retrieved_id]) ``` Observe que `input_type="document"` e `input_type="query"` são usados para gerar o embedding do documento e da consulta, respectivamente. Para mais informações sobre `input_type`, consulte [Quando e como devo usar o parâmetro input\_type?](https://platform.claude.com/docs/pt-BR/build-with-claude/embeddings#faq) nas perguntas frequentes. A saída é o quinto documento, que é de fato o mais relevante para a consulta: ```text wrap Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET. ``` Se você está procurando um conjunto detalhado de receitas sobre como fazer RAG com embeddings, incluindo bancos de dados vetoriais, confira a [receita de RAG](https://platform.claude.com/cookbook/third-party-pinecone-rag-using-pinecone). ## Perguntas frequentes Os modelos de embedding dependem de redes neurais poderosas para capturar e comprimir o contexto semântico, de forma semelhante aos modelos generativos. A equipe de pesquisadores experientes em IA da Voyage AI otimiza cada componente do processo de embedding, incluindo: * Arquitetura do modelo * Coleta de dados * Funções de perda * Seleção do otimizador Saiba mais sobre a abordagem técnica da Voyage AI no [blog da Voyage AI](https://blog.voyageai.com/). Para embeddings de uso geral, os modelos recomendados são: * `voyage-4-large`: Melhor qualidade * `voyage-4-lite`: Menor latência e custo * `voyage-4`: Desempenho equilibrado Para recuperação, use o parâmetro `input_type` para especificar se o texto é do tipo consulta ou documento. Modelos específicos de domínio: * Tarefas jurídicas: `voyage-law-2` * Recuperação de código e codificação agêntica: `voyage-code-4` * Tarefas relacionadas a finanças: `voyage-finance-2` Para recuperação no nível do chunk e no nível do documento: `voyage-context-4` Para texto, imagens e vídeo: `voyage-multimodal-3.5` Você pode usar os embeddings da Voyage AI com similaridade de produto escalar, similaridade de cosseno ou distância euclidiana. Para uma explicação sobre similaridade de embeddings, consulte este [guia de similaridade vetorial](https://www.pinecone.io/learn/vector-similarity/). Os embeddings da Voyage AI são normalizados para comprimento 1, o que significa que: * A similaridade de cosseno é equivalente à similaridade por produto escalar, sendo que esta última pode ser calculada mais rapidamente. * A similaridade de cosseno e a distância euclidiana resultam em classificações idênticas. Consulte [Tokenization](https://www.mongodb.com/docs/voyageai/tutorials/tokenization/) na documentação do MongoDB. Para todas as tarefas e casos de uso de recuperação (por exemplo, RAG), use o parâmetro `input_type` para especificar se o texto de entrada é uma consulta ou um documento. Não omita `input_type` nem defina `input_type=None`. Especificar se o texto de entrada é uma consulta ou um documento pode criar melhores representações vetoriais densas para recuperação, o que pode levar a uma melhor qualidade de recuperação. Ao usar o parâmetro `input_type`, prompts especiais são adicionados ao início do texto de entrada antes da geração do embedding. Especificamente: > 📘 **Prompts associados ao `input_type`** > > * Para uma consulta, o prompt é `"Represent the query for retrieving supporting documents: "`. > > * Para um documento, o prompt é `"Represent the document for retrieval: "`. > > * Exemplo > > * Quando `input_type="query"`, uma consulta como "When is Apple's conference call scheduled?" se tornará "**Represent the query for retrieving supporting documents:** When is Apple's conference call scheduled?" > * Quando `input_type="document"`, um documento como "Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET." se tornará "**Represent the document for retrieval:** Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET." A quantização em embeddings converte valores de alta precisão, como números de ponto flutuante de precisão simples de 32 bits, em formatos de menor precisão, como inteiros de 8 bits ou valores binários de 1 bit, reduzindo o armazenamento, a memória e os custos em 4x e 32x, respectivamente. Os modelos da Voyage AI compatíveis permitem a quantização especificando o tipo de dados de saída com o parâmetro `output_dtype`: * `float`: Cada embedding retornado é uma lista de números de ponto flutuante de precisão simples de 32 bits (4 bytes). Este é o padrão e oferece a maior precisão / exatidão de recuperação. * `int8` e `uint8`: Cada embedding retornado é uma lista de inteiros de 8 bits (1 byte) variando de -128 a 127 e de 0 a 255, respectivamente. * `binary` e `ubinary`: Cada embedding retornado é uma lista de inteiros de 8 bits que representam valores de embedding quantizados de bit único e empacotados em bits: `int8` para `binary` e `uint8` para `ubinary`. O comprimento da lista de inteiros retornada é 1/8 da dimensão real do embedding. O tipo binary usa o método binário com deslocamento (offset binary), como mostra o exemplo a seguir. > **Exemplo de quantização binária** > > Considere os seguintes oito valores de embedding: -0.03955078, 0.006214142, -0.07446289, -0.039001465, 0.0046463013, 0.00030612946, -0.08496094 e 0.03994751. Com a quantização binária, valores menores ou iguais a zero serão quantizados para um zero binário, e valores positivos para um um binário, resultando na seguinte sequência binária: 0, 1, 0, 0, 1, 1, 0, 1. Esses oito bits são então empacotados em um único inteiro de 8 bits, 01001101 (com o bit mais à esquerda como o bit mais significativo). > > * `ubinary`: A sequência binária é convertida diretamente e representada como o inteiro sem sinal (`uint8`) 77. > * `binary`: A sequência binária é representada como o inteiro com sinal (`int8`) -51, calculado usando o método binário com deslocamento (77 - 128 = -51). Para os modelos que suportam cada tipo de dados, consulte [Create text embeddings](https://www.mongodb.com/docs/api/doc/atlas-embedding-and-reranking-api/operation/operation-createembedding) na documentação da Atlas Embedding and Reranking API. O aprendizado Matryoshka cria embeddings com representações do mais grosseiro ao mais refinado dentro de um único vetor. Os modelos da Voyage AI que suportam múltiplas dimensões de saída, como o `voyage-code-4`, geram esses embeddings Matryoshka. Para obter vetores mais curtos da API, passe `output_dimension` (por exemplo, `output_dimension=256`). Para encurtar vetores que você já armazenou, trunque-os mantendo o subconjunto inicial de dimensões e, em seguida, normalize-os novamente. Por exemplo, o código Python a seguir demonstra como truncar vetores de 1024 dimensões para 256 dimensões: ```python import voyageai import numpy as np def embd_normalize(v: np.ndarray) -> np.ndarray: """ Normalize the rows of a 2D numpy array to unit vectors by dividing each row by its Euclidean norm. Raises a ValueError if any row has a norm of zero to prevent division by zero. """ row_norms = np.linalg.norm(v, axis=1, keepdims=True) if np.any(row_norms == 0): raise ValueError("Cannot normalize rows with a norm of zero.") return v / row_norms vo = voyageai.Client() # Gera vetores voyage-code-4, que por padrão são números de ponto flutuante com 1024 dimensões embd = vo.embed(["Sample text 1", "Sample text 2"], model="voyage-code-4").embeddings # Define uma dimensão menor short_dim = 256 # Redimensiona e normaliza os vetores para a dimensão menor resized_embd = embd_normalize(np.array(embd)[:, :short_dim]).tolist() ``` ## Preços Para os detalhes de preços mais atualizados, consulte [Model pricing](https://www.mongodb.com/docs/voyageai/management/billing/#model-pricing) na documentação do MongoDB.