A API de incorporação e reclassificação fornece acesso programático aos modelos de incorporação e reclassificação mais recentes do Voyage AI 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.
Gerenciamento de chaves de API
Você usa o 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 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 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 POST, 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 UI 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 demodelo para uso específico do modelo.
Especificação da API para obter detalhes completos sobre todos os endpoints 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 e recuperação semântica, defina input_type como query ou document para otimizar a forma como os modelos da Voyage AI 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 de 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__)"