Extender con un proveedor de IA personalizado
Esta es una referencia para desarrolladores para añadir un nuevo adaptador de proveedor de IA (modelo de texto, modelo de imagen o ambos) al motor de IA de Structura. Si solo intentas elegir un proveedor en wp-admin, mira Ajustes de IA.
El motor de IA de Structura usa un patrón adaptador: la pipeline (investigar → redactar → imagen) habla con un pequeño conjunto de interfaces agnósticas al proveedor, y cada proveedor concreto — OpenAI, Gemini, Anthropic, Cloud — las implementa. Añadir un nuevo proveedor significa escribir un adaptador que satisfaga esas interfaces y registrarlo con el motor.
Fuente de verdad: functions/src/ai/engine.ts,
specs/ai-provider-refactor-plan.md.
Lo que escribirás
Para un proveedor de texto:
- Una clase que implemente
TextProviderAdapter, con:id,displayName,supportedModels.generate(request): Promise<GenerationResult>— la llamada principal.estimateCost(request): Promise<CostEstimate>— usado para el seguimiento de cuota Cloud y la línea de coste post-generación en la página de Registros.validateKey(key)— usado por Structura → Ajustes → Motor de IA para confirmar que una clave pegada es válida antes de guardarla.
Para un proveedor de imagen:
- Una clase que implemente
ImageProviderAdapter, con:id,displayName,supportedSizes.generateImage(request): Promise<ImageResult>.validateKey(key).
La mayoría de adaptadores acaban siendo de 150 a 300 líneas
cada uno. Mira los OpenAIAdapter, GeminiAdapter y
AnthropicAdapter existentes para ver la forma.
Registrar el adaptador
- Añade el adaptador a la lista de exports en
functions/src/ai/providers/index.ts. - Añádelo al registro de proveedores del motor para que sea visible para la pipeline.
- Añade una entrada correspondiente en el paquete de
tipos compartido (
packages/types) para que la página de ajustes de Motor de IA del cliente pueda renderizar los campos de formulario adecuados. - Saca cualquier configuración específica del proveedor (p. ej. un override de URL base para modelos autoalojados) en el formulario de ajustes.
Pruebas
El patrón adaptador hace los adaptadores eminentemente testables:
- Haz pruebas unitarias contra fixtures grabados — sin llamadas API reales en CI.
- Añade pruebas de integración contra una clave de dev si es posible; protégelas tras una variable de entorno para que CI sin claves pueda saltarlas.
Mira functions/src/ai/__tests__/ para los patrones de
prueba existentes.
Lo que el motor entrega a tu adaptador
Una GenerationRequest se ve así:
prompt— los prompts de sistema + usuario ensamblados para esta etapa de la pipeline.model— el modelo preferido del llamador (tu adaptador puede vetar).temperature,maxTokens, etc.context— metadatos estructurados (ID de campaña, nombre de etapa) para tus registros, nunca alimentados al modelo.
Tu adaptador devuelve un GenerationResult con:
content— la salida del modelo.usage— tokens (o equivalente) consumidos.costUsd— tu coste calculado, para que el motor pueda registrar y cobrar con precisión.
Manejo de errores
Los adaptadores lanzan errores tipados:
AIAuthError— clave incorrecta, credencial revocada.AIRateLimitError— limitación transitoria.AIQuotaError— cuota agotada / problema de facturación.AIProviderError— comodín para otros 4xx/5xx.
El motor usa el tipo para decidir si reintenta, falla la ejecución o muestra un mensaje específico en la página de Registros.
Enviarlo
Una vez tu adaptador esté dentro y probado:
- Haz un commit
feat:. El changelog nombrará al proveedor automáticamente. - Actualiza Ajustes de IA con los pasos de configuración del nuevo proveedor (en ese punto estás escribiendo para usuarios finales, no desarrolladores).