A API de incorporação e reclassificação fornece acesso programático aos modelos de incorporação e reclassificação mais recentes do Voyage IA por meio de uma interface RESTful. Esta página fornece uma visão geral da API e seus recursos.
Para obter informações e parâmetros detalhados, consulte a especificação da API.
Dica
Restringir o acesso ao projeto à Embedding and Reranking API.
You can create an Atlas Resource Policy to restrict access to the Embedding and Reranking API for all or some projects in your organization. To learn more, see Atlas Resource Policies
Gerenciamento de chaves de API
Você usa MongoDB Atlas para gerenciar chaves de API para a API de incorporação e reclassificação. Isso inclui criar e gerenciar suas chaves de API de modelo em sua organização e projetos, monitorar o uso e configurar limites de taxa.
Para aprender mais, consulte Gerenciar chaves de API do modelo Voyage AI.
Observação
Ele é nomeado chave de API do modelo para diferenciá-lo de outras chaves de API no Atlas. Use essa chave da mesma forma que as chaves API de outros fornecedores de modelos.
Autenticação
Todas as solicitações para a API de incorporação e reclassificação devem incluir um cabeçalho Authorization com sua chave de API do modelo usando o formato de token do portador.
Authorization: Bearer VOYAGE_API_KEY
Ao usar um SDK de cliente, você define a chave de API ao construir um, e o SDK envia o cabeçalho em seu nome com cada solicitação. Ao integrar diretamente com a API, você mesmo deve enviar este cabeçalho.
Endpoints
O escopo da chave API do seu modelo determina o ponto de extremidade para o qual você envia solicitações. Uma chave com escopo para uma Geografia funciona apenas contra o ponto de extremidade dessa Geografia, e uma chave sem escopo funciona contra o ponto de extremidade sem escopo.
Endpoint | Geograficamente |
|---|---|
| Não delimitado. O Atlas pode servir à solicitação de qualquer geografia. |
| Europa |
| Estados Unidos |
Pontos de extremidade com escopo seguem o padrão <geography>.ai.mongodb.com, onde <geography> é o valor geography da chave de API do modelo que você envia com a solicitação.
Se você enviar uma chave com escopo para um ponto de extremidade que não corresponde ao seu escopo, a solicitação falha. O Atlas não redireciona a solicitação para o ponto de extremidade que corresponde à chave.
Os pontos de extremidade com escopo diferem do ponto de extremidade sem escopo das seguintes maneiras:
O Atlas cobra uma sobretaxa de 10% sobre os tokens que você envia para um ponto de extremidade com escopo.
Pontos de extremidade com escopo exigem um tier de uso pago e começam no tier de uso 1. Para usar um tier de uso mais alto com um ponto de extremidade com escopo, contato sua equipe de contas. Para aprender mais sobre tiers de uso, consulte Tiers de uso.
Os pontos de extremidade com escopo têm seus próprios limites de taxa, que são mais baixos do que os do ponto de extremidade sem escopo. Para saber mais, consulte Limites de taxa de geografia.
Os pontos de extremidade com escopo não servem todos os modelos. Para verificar quais pontos de extremidade servem um determinado modelo, consulte a coluna Pontos de extremidade com suporte das tabelas de modelo em Model Deprecations, Lifecycle States, and Support.
Para aprender o que é uma Geografia e quando usar uma, consulte Geografias para inferência do Voyage AI.
JSON
Todas as entidades são representadas noJSON. Aplicam-se as seguintes regras e convenções:
- Cabeçalho de solicitação de tipo de conteúdo
- Ao enviar JSON para o servidor com uma solicitação publicação, especifique o cabeçalho
Content-Type: application/json. Os SDKs do cliente lidam com isso automaticamente. - Solicitações inválidas
- Se você tentar criar uma solicitação com JSON inválido, tipos de dados incorretos ou violações de restrições (como exceder os limites de token ou os tamanhos de lote ), o servidor responderá com um código de status
400e uma mensagem de erro descrevendo o problema. - Nomes de campo para campos com números
- Os campos que contêm valores numéricos são nomeados para desambiguar a unidade que está sendo usada. Por exemplo, as contagens de token são especificadas em campos como
total_tokenseoutput_dimensionpara esclarecer a unidade de medida.
Limites de taxa e níveis de uso
A API de incorporação e reclassificação implementa limitação de taxa para garantir o uso leal e o desempenho ideal. Os limites de taxa são aplicados por chave API e medidos em duas dimensões. Seus limites de taxa aumentam à medida que você avança nos níveis de uso.
TPM (Tokens Per Minuto): número máximo de tokens processados por minuto
RPM (Solicitações por minuto): número máximo de solicitações de API por minuto
Se você exceder o limite de taxa, a API retornará um código de status HTTP 429 (Limite de taxa excedido).
Os limites da taxa de teste gratuito sem um método de pagamento são 3 RPM e 10K TPM. Para se qualificar para limites de taxa mais altos, adicione uma forma de pagamento à sua conta.
Modelo | Tokens Per Min (TPM) | Solicitações por minuto (RPM) |
|---|---|---|
| 16,000,000 | 2,000 |
| 8,000,000 | 2,000 |
| 3,000,000 | 2,000 |
| 3,000,000 | 2,000 |
| 2,000,000 | 2,000 |
| 4,000,000 | 2,000 |
| 2,000,000 | 2,000 |
Os limites de taxa do nível de uso 2 são o dobro do nível de uso 1.
Modelo | Tokens Per Min (TPM) | Solicitações por minuto (RPM) |
|---|---|---|
| 32,000,000 | 4,000 |
| 16,000,000 | 4,000 |
| 6,000,000 | 4,000 |
| 6,000,000 | 4,000 |
| 4,000,000 | 4,000 |
| 8,000,000 | 4,000 |
| 4,000,000 | 4,000 |
Os limites de taxa do nível de uso 3 são três vezes maiores que os do nível de uso 1.
Modelo | Tokens Per Min (TPM) | Solicitações por minuto (RPM) |
|---|---|---|
| 48,000,000 | 6,000 |
| 24,000,000 | 6,000 |
| 9,000,000 | 6,000 |
| 9,000,000 | 6,000 |
| 6,000,000 | 6,000 |
| 12,000,000 | 6,000 |
| 6,000,000 | 6,000 |
Para saber mais sobre os níveis de uso, consulte Níveis de uso.
Para definir limites de taxa personalizados para sua organização, use a IU do Atlas. Para saber mais, consulte Gerenciar Limites de Taxa.
Fazer solicitações
O exemplo a seguir demonstra como você pode usar cURL para fazer uma solicitação ao serviço de incorporação. Você também pode usar um cliente HTTP em qualquer linguagem de programação para acessar a API.
Para exemplos de uso adicionais, consulte os seguintes recursos:
Acessando os modelos de IA do Voyage para solicitações HTTP e exemplos de SDK do cliente
Páginas de modelo para uso específico do modelo.
Especificação da API para obter detalhes completos sobre todos os pontos de extremidade da API.
curl \ --request POST 'https://ai.mongodb.com/v1/embeddings' \ --header "Authorization: Bearer $VOYAGE_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "input": [ "MongoDB is redefining what a database is in the AI era.", "Voyage AI embedding and reranking models are state-of-the-art." ], "model": "voyage-4-large" }'
Errors
To learn more about errors returned by the API, see the API specification.
Melhores práticas
Considere as seguintes práticas recomendadas ao usar a API:
Especificando tipo de entrada
Para tarefas de pesquisa semântica e recuperação, defina input_type como query ou document para otimizar a forma como os modelos da Voyage IA criam os vetores. Não omita este parâmetro.
O parâmetro adiciona os seguintes prompts à sua entrada antes de gerar incorporações:
query: "Representar a query para recuperar documentos de suporte: "document: "Representar o documento para recuperação: "
Exemplo
input_type="query" transforma "Para quando a chamada em conferência da Apple está agendada?" em "Represente a consulta para recuperar documentos de suporte: para quando está programada a chamada em conferência da Apple?"
Solução de problemas
Se você estiver usando o cliente Python, deverá usar a versão 0.3.7 ou posterior. Para verificar a versão da instalação do cliente Python, execute o seguinte comando no seu terminal:
python -c "import voyageai; print(voyageai.__version__)"