Ir al contenido principal
Español— Elegir un idioma
Menú

Permisos y límites de las colecciones

Lección 8 de 16 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. El riesgo específico de las bases de conocimiento
  2. Dos claves, dos roles
  3. El permiso AddFileToCollection
  4. Cuotas y sus costes
  5. Aislar, rotar y monitorizar
  6. Un archivo, múltiples colecciones
  7. Puntos clave

El riesgo específico de las bases de conocimiento

Una base de conocimiento empresarial nunca es trivial: contiene notas internas, informes confidenciales y contratos en fase de negociación. Si los controles de acceso fallan, no solo se filtra un archivo aislado, sino que se expone la base completa, dotada además de un motor de búsqueda para localizar lo importante. El sistema de permisos de xAI mitiga este riesgo separando los derechos, mientras que las cuotas regulan el uso y la facturación.

Dos claves, dos roles

El ecosistema de xAI se basa en dos credenciales con ámbitos distintos:

ClaveUsoÁmbito
XAI_API_KEYCarga de archivos y búsquedaOperaciones de lectura y uso
XAI_MANAGEMENT_API_KEYGestión de coleccionesOperaciones de administración

Esta separación aplica concretamente el principio de mínimo privilegio. Un desarrollador que conecta un chatbot de soporte a tu base necesita consultar la colección, nunca eliminarla. Al proporcionarle únicamente la clave estándar, un error en el script o una clave comprometida no podrán destruir un índice construido durante meses.

El permiso AddFileToCollection

Una clave de API de gestión (Management API Key) no tiene todos los poderes por defecto. Sus derechos son explícitos, y el más crítico para las colecciones es AddFileToCollection. Sin él, puedes crear y listar colecciones, pero no añadir ni un solo documento; una situación confusa, ya que todo parece funcionar hasta el momento de la ingestión. La generación de una clave correcta implica cuatro pasos:

  1. Inicia sesión en la consola de xAI
  2. Crea una nueva clave de API de gestión (Management API Key)
  3. Activa el permiso AddFileToCollection
  4. Almacena la clave de forma segura: variable de entorno o gestor de secretos

Cuando falta el permiso, la API es explícita y devuelve un 403:

{
  "error": {
    "message": "Insufficient permissions",
    "type": "permission_error",
    "code": 403
  }
}

Tu primer paso debe ser verificar los derechos de la clave en la consola en lugar de sospechar de la solicitud, cuya sintaxis no tiene nada que ver con el rechazo.

Cuotas y sus costes

Tres topes rigen el almacenamiento por cuenta: 100.000 archivos en total, 100 GB de capacidad acumulada y 100 MB por archivo individual en las colecciones; más del doble de los 48 MB permitidos solo por la API de archivos (Files API), lo que te permite incluir documentos que no podrías enviar como adjuntos directos.

En el lado de la facturación, destacan dos conceptos: las búsquedas en colecciones (Collections Search) se facturan a 2,50 $ por cada 1.000 llamadas de búsqueda, mientras que los adjuntos de archivos (File Attachments) cuestan 10 $ por cada 1.000 llamadas. La diferencia es significativa y pesa en las decisiones arquitectónicas. Bajo un uso intensivo, consultar una colección indexada cuesta considerablemente menos que volver a adjuntar el mismo documento con cada pregunta.

Si tus necesidades superan estas cuotas, el soporte de xAI puede conceder un aumento. Prepara tu solicitud con cifras concretas —número objetivo de archivos, volumen total, frecuencia de búsqueda esperada— en lugar de con una estimación vaga. Esto agiliza el procesamiento de la solicitud.

Aislar, rotar y monitorizar

La primera práctica concierne a las claves. Asigna claves diferentes a cada entorno, de modo que un script de desarrollo nunca pueda tocar la base de producción. No entregues nunca una clave de gestión (Management key) a un servicio cuya única necesidad sea la búsqueda. Y rota estas claves regularmente, especialmente después de que un colaborador con acceso a los secretos abandone la empresa.

La segunda concierne a la estructura. En lugar de una única colección donde coexistan documentación pública y contratos, separa tus bases por nivel de confidencialidad: una base «pública» para documentación abierta, una base «interna» para documentos de la empresa y una base «confidencial» para datos sensibles. Cada servicio recibe entonces solo el acceso que necesita, y la pregunta «¿puede este chatbot citar un contrato?» queda respondida por diseño.

La tercera es la monitorización. Revisa tu consumo en la consola de xAI, configura una alerta ante cualquier subida inesperada del volumen de búsquedas —a menudo el primer signo de un bucle descontrolado— y mantén un registro escrito de qué servicios acceden a qué colecciones.

Un archivo, múltiples colecciones

Este aislamiento no requiere duplicar tus documentos, ya que el mismo archivo puede pertenecer a varias colecciones. Un informe técnico aparece así en «product-documentation» para el equipo técnico, en «quarterly-reports» para la dirección y en «support-base» para el servicio de atención al cliente. Se almacena una sola vez, cuenta una sola vez hacia tus cuotas y permanece buscable en los tres contextos: vistas temáticas por audiencia, sin copias divergentes.

Puntos clave

  • Dos claves de API distintas: estándar para el uso, de gestión (Management) para la administración
  • El permiso AddFileToCollection es esencial para poblar las colecciones
  • Los límites son 100.000 archivos, 100 GB y 100 MB por archivo
  • Separa tus colecciones por nivel de confidencialidad
  • Un archivo puede pertenecer a varias colecciones sin duplicación