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 à Embedding and Reranking API para todos ou alguns projetos em sua organização. Para saber mais, consulte 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 aprender mais, consulte Chaves de API do modelo.
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.
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__)"