La API de inserción y reordenación ofrece acceso programático a los modelos más recientes de inserción y reordenación de Voyage IA a través de una interfaz RESTful. Esta página ofrece una visión general de la API y sus funcionalidades.
Para obtener información detallada y parámetros, consulta la Especificación de la API.
Gestión de claves API
Utilizas MongoDB Atlas para gestionar las claves API para la API de Embedding y Reranking. Esto incluye crear y gestionar tus claves de API de modelo en toda tu organización y proyectos, supervisión del uso y configurar límites de tasa.
Para aprender más, Claves API del modelo.
Nota
Se le llama clave de API de modelo para distinguirla de otras claves de API en Atlas. Utiliza esta clave de la misma manera que las claves de API de otros proveedores de modelos.
Autenticación
Todas las solicitudes a Embedding y Reranking API deben incluir un
Authorization cabecera con tu clave API de modelo usando el formato de token Bearer.
Authorization: Bearer VOYAGE_API_KEY
Cuando utilices un SDK de cliente, configuras la clave de API al crear un cliente, y el SDK envía el encabezado en tu nombre con cada solicitud. Cuando se integra directamente con la API, debe enviar este encabezado usted mismo.
JSON
Todas las entidades están representadas en JSON. Se aplican las siguientes reglas y convenciones:
- Encabezado de solicitud de tipo de contenido
- Cuando envíes JSON al servidor con una publicación, especifica el encabezado
Content-Type: application/json. Los SDK del cliente gestionan esto automáticamente. - Solicitudes no válidas
- Si intentas crear una solicitud con JSON no válido, tipos de datos incorrectos o restricciones que se violen (como exceder los límites de tokens o tamaños de lote), el servidor responde con un código de estado
400y un mensaje de error que describe el problema. - Nombres de campos para campos con números
- Los campos que contienen valores numéricos se nombran para desambiguar la unidad utilizada. Por ejemplo, los recuentos de tokens se especifican en campos como
total_tokensyoutput_dimensionpara aclarar la unidad de medida.
Límites de frecuencia y niveles de uso
La API de Embedding y Reranking implementa limitaciones de tasa para garantizar el uso justo y el rendimiento óptimo. Los límites de tasa se aplican por cada clave API y se miden en dos dimensiones. Sus límites de tasa aumentan a medida que avanza a través de los niveles de uso.
TPM (Tokens por minuto): Número máximo de tokens procesados por minuto
RPM (solicitudes por minuto): Número máximo de solicitudes a la API por minuto
Si se supera el límite de tasa, la API devuelve un 429 (límite de tasa superado) código de estado HTTP.
Los límites de prueba gratuita sin un método de pago son 3 RPM y 10K TPM. Para calificar para límites de tasas más altos, añade un método de pago a tu cuenta.
Modelo | Tokens Per Min (TPM) | Solicitudes 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 |
Los límites de tasa para el nivel de uso 2 son el doble que los del nivel de uso 1.
Modelo | Tokens Per Min (TPM) | Solicitudes 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 |
Los límites de velocidad para el nivel de uso 3 son tres veces los del nivel de uso 1.
Modelo | Tokens Per Min (TPM) | Solicitudes 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 aprender más sobre los niveles de uso, consulta Niveles de uso.
Para establecer límites de tasa personalizados para tu organización, utiliza la interfaz de usuario Atlas. Para obtener más información, consulte Gestionar límites de tasa.
Realización de solicitudes
El siguiente ejemplo muestra cómo usar cURL para realizar una solicitud al servicio de incrustación. También puede usar un cliente HTTP en cualquier lenguaje de programación para acceder a la API.
Para obtener ejemplos de uso adicionales, consulte los siguientes recursos:
Acceso a modelos de Voyage AI para solicitudes HTTP y ejemplos de SDK de cliente
Páginas de modelo para instrucciones de uso específicas del modelo.
Consulta la especificación de API para obtener todos los detalles sobre los endpoints de la 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 obtener más información sobre los errores devueltos por la API, consulta la especificación de la API.
Mejores prácticas
Tenga en cuenta las siguientes prácticas recomendadas al utilizar la API:
Especificando el tipo de entrada
Para las tareas de búsqueda semántica y recuperación, establece el input_type en query o document para optimizar cómo los modelos de Voyage AI crean los vectores. No omitas este parámetro.
El parámetro añade las siguientes indicaciones a la entrada antes de generar incrustaciones:
query: "Representa la query para recuperar documentos de respaldo: "document: "Representar el documento para su recuperación: "
Ejemplo
input_type="query" transforma "¿Cuándo está programada la conferencia telefónica de Apple?" en "Representa la consulta para recuperar documentos de respaldo: ¿Cuándo está programada la conferencia telefónica de Apple?"
Solución de problemas
Si utiliza el cliente de Python, debe usar la versión 0.3.7 o posterior. Para comprobar la versión de la instalación del cliente de Python, ejecute el siguiente comando en su terminal:
python -c "import voyageai; print(voyageai.__version__)"