La API de Integración y Reclasificación proporciona acceso programático a los modelos de integración y reclasificación más recientes de Voyage AI mediante una interfaz RESTful. Esta página ofrece una descripción general de la API y sus funciones.
Para obtener información detallada y parámetros, consulte la especificación API.
Gestión de claves API
Utilice MongoDB Atlas para administrar las claves API de la API de Integración y Reclasificación. Esto incluye la creación y administración de las claves API de su modelo en toda su organización y proyectos, la supervisión del uso y la configuración de límites de velocidad.
Para obtener más información, consulte Claves API del modelo.
Nota
Se denomina clave API de modelo para distinguirla de otras claves API en Atlas. Se utiliza de la misma manera que las claves API de otros proveedores de modelos.
Autenticación
Todas las solicitudes a la API de incrustación y reclasificación deben incluir una
Authorization encabezado con su clave API de modelo utilizando el formato de token Bearer.
Authorization: Bearer VOYAGE_API_KEY
Al usar un SDK de cliente, se configura la clave API al crear un cliente, y el SDK envía el encabezado en su nombre con cada solicitud. Al integrar directamente con la API, debe enviar este encabezado usted mismo.
JSON
Todas las entidades se representan 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 intenta crear una solicitud con JSON no válido, tipos de datos incorrectos o violaciones de restricciones (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 velocidad y niveles de uso
La API de Integración y Reclasificación implementa límites de velocidad para garantizar un uso justo y un rendimiento óptimo. Estos límites se aplican por clave API y se miden en dos dimensiones. Los límites de velocidad aumentan a medida que se avanza en 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 de 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 tarifa de prueba gratuita sin método de pago son 3 RPM y 10K TPM. Para acceder a límites de tarifa más altos, agregue un método de pago a su 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 velocidad para el nivel de uso 2 son el doble de 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 obtener más información sobre los niveles de uso, consulte Niveles de uso.
Para establecer límites de velocidad personalizados para su organización, utilice la interfaz de usuario de Atlas. Para obtener más información, consulte Administrar límites de velocidad.
Realizar 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 modelos para uso específico 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, consulte la especificación de la API.
Mejores prácticas
Tenga en cuenta las siguientes prácticas recomendadas al utilizar la API:
Especificación del tipo de entrada
Para tareas de búsqueda y recuperación semántica, configure input_type en query o document para optimizar la creación de vectores por parte de los modelos de Voyage AI. No omita 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 usa el cliente de Python, debe usar la versión 0.3.7 o posterior. Para comprobar la versión de su cliente de Python, ejecute el siguiente comando en su terminal:
python -c "import voyageai; print(voyageai.__version__)"