Administrar claves de API de modelos de Voyage AI

Las claves API de modelo sirven como mecanismo de autenticación y autorización para la API de Embedding y Reranking, y te permiten acceder a los modelos de Voyage AI a través de la API. Esta página describe cómo crear y administrar las claves API en la Interfaz de Usuario de Atlas.

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.

Crea y gestiona las claves API del modelo

Puedes crear y gestionar claves API de modelo desde la interfaz de usuario de Atlas a nivel de organización y proyecto. Se aplican límites de velocidad a las claves de la API en función de si las creaste a nivel de organización o de proyecto.

Permisos requeridos

Para crear, actualizar y borrar claves API del modelo:

A nivel de organización, debes Organization Owner tener acceso a Atlas.
A nivel de proyecto, debes tener Project Model Owner, Project Owner o acceso superior a Atlas.

Para ver las claves API del modelo:

A nivel organizativo y de proyecto, debes tener Organization Read Only o un nivel de acceso superior a Atlas.
Solo a nivel de proyecto, debes tener acceso Project Read Only o superior a Atlas.

Para obtener una lista completa de permisos para cada rol, consulte Acceso a la organización y el proyecto.

Crear una clave API.

Cuando crees una clave API de modelo a nivel de organización, vincula la clave a un proyecto. Después de crear la clave, no podés cambiar a qué proyecto está vinculada la clave. Se aplican límites de tasa a cada clave en el proyecto.

Nota

Si crea una clave de API de modelo a través de Atlas, como se describe en el siguiente procedimiento, la clave autentica las solicitudes a los puntos finales ai.mongodb.com. Por el contrario, si crea una clave directamente a través de Voyage AI, la clave autentica las solicitudes a https://api.voyageai.com/v1/embeddings.

También se define el ámbito de la clave al crearla. Para obtener más información, consulte Ámbito de la clave.

Para crear claves API de modelos a nivel de la organización, complete los siguientes pasos:

Inicia sesión en Atlas.

Ve a la página AI Model APIs en la Interfaz de Usuario de Atlas.

Si aún no se muestra, selecciona la organización deseada en el menú Organizations de la barra de navegación.
A nivel de organización, haz clic en Model API Keys bajo el encabezado Services en la barra de navegación.

Crea la clave API del modelo.

Haga clic en Create new model API key.
Introduce un nombre para la clave.
Las claves API del modelo no pueden exceder los 250 caracteres.
Selecciona un proyecto del menú desplegable para enlazarlo con la clave API.
Seleccione un proveedor de nube del menú desplegable Cloud provider.
Seleccione any para dejar la dimensión de la nube sin alcance.
opcional. Seleccione una geografía del menú desplegable Geography.
La mayoría de las claves no necesitan una geografía. Seleccione any para dejar la dimensión de geografía sin alcance.
Atlas muestra el API Endpoint de solo lectura para el ámbito que seleccione. La clave se autentica en este endpoint.
Haga clic en Create.

Guardar la clave API.

Copia la clave de API del modelo y almacénala en una ubicación segura.
Después de salir de la página donde se muestra la clave, no podrás verla de nuevo. Si la pierdes, crea otra nueva.
Haga clic en Done.

Para crear claves API de modelos a nivel de proyecto, completa los siguientes pasos:

Inicia sesión en Atlas.

Ve a la página AI Model APIs en la Interfaz de Usuario de Atlas.

Si aún no se muestra, selecciona la organización deseada en el menú Organizations de la barra de navegación.
Si aún no aparece, selecciona el proyecto deseado en el menú Projects de la barra de navegación.
A nivel de proyecto, haz clic en AI Model APIs en el encabezado Services de la barra de navegación.

Crea la clave API del modelo.

Si aún no se muestra, selecciona Model API Keys en la barra de navegación.
Haga clic en Create model API key.
Introduce un nombre para la clave.
Las claves API del modelo no pueden exceder los 250 caracteres.
Seleccione un proveedor de nube del menú desplegable Cloud provider.
Seleccione any para dejar la dimensión de la nube sin alcance.
opcional. Seleccione una geografía del menú desplegable Geography.
La mayoría de las claves no necesitan una geografía. Seleccione any para dejar la dimensión de geografía sin alcance.
Atlas muestra el API Endpoint de solo lectura para el ámbito que seleccione. La clave se autentica en este endpoint.
Haga clic en Create.

Guardar la clave API.

Copia la clave de API del modelo y almacénala en una ubicación segura.
Después de salir de la página donde se muestra la clave, no podrás verla de nuevo. Si la pierdes, crea otra nueva.
Haga clic en Done.

Alcance de la clave

Nota

Vista previa pública

La geografía de Europa y su endpoint, eu.ai.mongodb.com, están disponibles como funcionalidad de vista previa pública. La funcionalidad y la documentación correspondiente pueden cambiar en cualquier momento durante el período de vista previa.

Cuando crea una clave de API de modelo, proporciona un cloud y un geography. Juntos, estos establecen el alcance de la clave, que determina el endpoint con el que se autentica la clave.

Establece cualquiera de los valores en any para dejar esa dimensión sin alcance. Una clave con cloud y geography establecidos en any es una clave sin alcance y funciona contra ai.mongodb.com.

Endpoint	Geografía
`ai.mongodb.com`	Sin ámbito. Atlas puede servir la solicitud desde cualquier geografía.
`eu.ai.mongodb.com`	Europa
`us.ai.mongodb.com`	Estados Unidos

Los puntos finales con ámbito siguen el patrón <geography>.ai.mongodb.com, donde <geography> es el valor geography de la clave API del modelo que envía con la solicitud.

Para saber qué es una geografía y cuándo limitar una clave a una, consulte Geografías para la inferencia de Voyage AI.

Tenga en cuenta lo siguiente al definir el ámbito de una clave:

El alcance es fijo cuando creas la clave. Para utilizar una nube o geografía diferente, borra la clave y crea una nueva. Una solicitud PATCH a una clave de API de modelo solo cambia el nombre de la clave.
El prefijo de clave codifica el alcance. Por ejemplo, una clave con alcance en Europa comienza con al-eu-. Utilice el prefijo para identificar el alcance de una clave sin volver a crearla.
Las claves con alcance requieren un nivel de uso de pago. No puedes definir el alcance de una clave en la prueba gratuita. Para aprender más, consulta Niveles de uso.

las claves de API de modelo que creó antes de que las geografías estuvieran disponibles se leen como cloud=any y geography=any. Estas claves siguen funcionando con ai.mongodb.com y no se migran. Para utilizar un ámbito, cree una nueva clave.

Restringir el alcance de la clave API del modelo mediante una política de recursos

Puede configurar una política de recursos a nivel de organización para exigir que las nuevas claves de API de modelo se creen en una nube determinada, una geografía determinada o ambas. Para ello, agregue una regla forbid escrita en Cedar que tenga como objetivo la acción de la Embedding and Reranking API.

Esta política rige la creación de claves. No restringe el uso de una clave existente. Si configura esta política, los usuarios no podrán crear claves fuera del ámbito permitido. Sin embargo, la política no revoca ni modifica el ámbito de las claves ya existentes. Estas claves seguirán funcionando. Para eliminar una clave anterior a la implementación de la política, consulte la sección «Eliminar una clave de API».

Puedes permitir ámbitos específicos mediante el uso de la cláusula unless en la regla forbid.

Ejemplo: Restringir el alcance de la clave de API del modelo con excepciones

forbid (principal, action == ResourcePolicy::Action::"project.aiModelAPI.modify", resource) unless { <exception> };

Para restringir las llaves a una geografía, utilice el atributo context.aiModelApi.geography en la cláusula unless. La siguiente política permite a los usuarios crear llaves de API de modelo solo para la geografía de Europa:

Ejemplo: Restringir las claves de API del modelo a la geografía de Europa

forbid (principal, action == ResourcePolicy::Action::"project.aiModelAPI.modify", resource) unless { context.aiModelApi.geography == ResourcePolicy::Geography::"eu" };

Para obtener más información sobre cómo configurar la política de recursos, consulte la descripción general de las políticas de recursos de Atlas.

Ver una clave de API

Los propietarios de la organización pueden ver y editar todas las claves de API de modelo de la organización a nivel de organización. Los propietarios de proyectos solo pueden ver y editar las claves API del modelo de los proyectos a los que tienen acceso.

Para ver las claves API del modelo a nivel de organización, completa los siguientes pasos:

Inicia sesión en Atlas.

Ve a la página AI Model APIs en la Interfaz de Usuario de Atlas.

Si aún no se muestra, selecciona la organización deseada en el menú Organizations de la barra de navegación.
A nivel de organización, haz clic en Model API Keys bajo el encabezado Services en la barra de navegación.

Para cada clave de API de modelo, la página muestra lo siguiente:

Nombre de columna	Descripción del valor de la columna
Name	Nombre de la clave API del modelo.
Secret Key	Clave de API de modelo redactada asociada con el nombre de la clave de API de modelo.
Created On (UTC)	Fecha en UTC en la que el usuario creó la clave de API del modelo.
Last Used (UTC)	Fecha en UTC en que se utilizó por última vez la clave de API del modelo. El valor es `Never` si la clave es nueva o nunca se ha utilizado.
Project	Nombre del Proyecto que está vinculado con la clave API del modelo.
Created By	Nombre del usuario que creó la clave.
Actions	Acciones que puede realizar en la clave. Puedes hacer clic en: para editar la clave API del modelo. para borrar la clave API del modelo.

Para ver las claves API del modelo a nivel de proyecto, completa los siguientes pasos:

Inicia sesión en Atlas.

Ve a la página AI Model APIs en la Interfaz de Usuario de Atlas.

Si aún no se muestra, selecciona la organización deseada en el menú Organizations de la barra de navegación.
Si aún no aparece, selecciona el proyecto deseado en el menú Projects de la barra de navegación.
A nivel de proyecto, haz clic en AI Model APIs en el encabezado Services de la barra de navegación.

Para cada clave API del modelo, la página muestra la siguiente información sobre la clave:

Nombre de columna	Descripción del valor de la columna
Name	Nombre de la clave API del modelo.
Secret Key	Clave de API de modelo redactada asociada con el nombre de la clave de API de modelo.
Created On (UTC)	Fecha en UTC en la que el usuario creó la clave de API del modelo.
Last Used (UTC)	Fecha en UTC en que se utilizó por última vez la clave de API del modelo. El valor es `Never` si la clave es nueva o nunca se ha utilizado.
Project	Nombre del Proyecto que está vinculado con la clave API del modelo.
Created By	Nombre del usuario que creó la clave.
Actions	Acciones que puede realizar en la clave. Puedes hacer clic en: para editar la clave API del modelo. para borrar la clave API del modelo.

Editar una clave API

Para editar las claves API del modelo a nivel de la organización, se deben completar los siguientes pasos:

Inicia sesión en Atlas.

Ve a la página AI Model APIs en la Interfaz de Usuario de Atlas.

Si aún no se muestra, selecciona la organización deseada en el menú Organizations de la barra de navegación.
A nivel de organización, haz clic en Model API Keys bajo el encabezado Services en la barra de navegación.

Edita la clave.

En la columna Actions, haz clic en correspondiente a la clave que deseas editar.
En la página Edit Model API Key, modifica el nombre de la clave API del modelo.
el nombre de la clave de la API del modelo debe ser único para el proyecto y puede tener hasta 250 caracteres de longitud.
Haz clic en Save para aplicar los cambios.

Para editar las claves API del modelo a nivel de proyecto, completa los siguientes pasos:

Inicia sesión en Atlas.

Ve a la página AI Model APIs en la Interfaz de Usuario de Atlas.

Si aún no se muestra, selecciona la organización deseada en el menú Organizations de la barra de navegación.
Si aún no aparece, selecciona el proyecto deseado en el menú Projects de la barra de navegación.
A nivel de proyecto, haz clic en AI Model APIs en el encabezado Services de la barra de navegación.

Edita la clave.

En la columna Actions, haz clic en correspondiente a la clave que deseas editar.
En la página Edit Model API Key, modifica el nombre de la clave API del modelo.
El nombre debe ser único en el proyecto y puede tener hasta 250 caracteres de longitud.
Haz clic en Save para aplicar los cambios.

Borrar una clave de API

Cuando borra una clave de API de modelo, MongoDB desactiva inmediatamente la clave y rechaza cualquier solicitud de API realizada con la clave eliminada. Una vez que borres la clave, no podrás verla, restaurarla ni modificarla.

Para borrar claves API de modelos a nivel de organización, complete los siguientes pasos:

Inicia sesión en Atlas.

Ve a la página AI Model APIs en la Interfaz de Usuario de Atlas.

Si aún no se muestra, selecciona la organización deseada en el menú Organizations de la barra de navegación.
A nivel de organización, haz clic en Model API Keys bajo el encabezado Services en la barra de navegación.

Borrar la clave.

En la columna Actions, haga clic en correspondiente a la clave que desea borrar.
En la ventana de confirmación, haz clic en Delete key para borrar la clave.

Para borrar claves de API de modelo a nivel de proyecto, completa los siguientes pasos:

Inicia sesión en Atlas.

Ve a la página AI Model APIs en la Interfaz de Usuario de Atlas.

Si aún no se muestra, selecciona la organización deseada en el menú Organizations de la barra de navegación.
Si aún no aparece, selecciona el proyecto deseado en el menú Projects de la barra de navegación.
A nivel de proyecto, haz clic en AI Model APIs en el encabezado Services de la barra de navegación.

Borrar la clave.

En la columna Actions, haga clic en correspondiente a la clave que desea borrar.
En la ventana de confirmación, haz clic en Delete key para borrar la clave.

Próximos pasos

Después de crear una clave API de modelo, podrá:

Establece límites de tasa para las claves de API de tu modelo.
Supervisa el uso de la clave de la API en tiempo real.

Acceso a la organización y al proyecto