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.
Você pode criar uma Política de Recursos do Atlas para restringir o acesso à API de Incorporação e Reclassificação para todos ou alguns projetos em sua organização. Para saber mais, consulte as Políticas de recursos do Atlas
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 saber 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
Observação
Visualização pública
A região geográfica da Europa e seu endpoint, eu.ai.mongodb.com, estão disponíveis como um recurso de visualização pública. O recurso e a documentação correspondente podem mudar a qualquer momento durante o período de Pré-visualização.
O escopo da chave de API do modelo determina o endpoint para o qual você envia solicitações. Uma chave com escopo para uma geográfica funciona somente no ponto de extremidade dessa região, e uma chave sem escopo funciona no ponto de extremidade sem escopo.
Endpoint | Geograficamente |
|---|---|
| Sem escopo. O Atlas pode atender à solicitação de qualquer localização geográfica. |
| Europa |
| Estados Unidos |
Os endpoints com escopo seguem o padrão <geography>.ai.mongodb.com, em que <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 endpoint que não corresponde a seu escopo, a solicitação falhará. O Atlas não redireciona a solicitação para o endpoint que corresponde à chave.
Os endpoints com escopo diferem do endpoint sem escopo das seguintes maneiras:
O Atlas cobra um aumento de 10% nos tokens que você envia para um endpoint com escopo.
Os endpoints com escopo definido exigem um nível de uso pago e começam no nível de 1 uso. Para usar um nível de uso mais alto com um endpoint com escopo, entre em contato com sua equipe de conta. Para saber mais sobre os níveis de uso, consulte Níveis de uso.
Os endpoints com escopo têm seus próprios limites de taxa, que são inferiores aos do endpoint sem escopo. Para saber mais, consulte Limites de taxa geográfica.
Os endpoints com escopo não atendem a todos os modelos. Para verificar quais endpoints atendem a um determinado modelo, consulte a coluna Endpoints compatíveis das tabelas de modelo em Descontinuações do modelo, Estados do ciclo de vida e Suporte.
Para saber o que é uma geográfica e quando usar uma, consulte Geographies for Voyage AI Inference.
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
Para saber mais sobre os erros retornados pela API, consulte a especificação da API.
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__)"