Documentación · Documentación técnica

Notas técnicas del AI Assistant

Este documento describe la característica opcional AI Assistant, que genera descripciones de vehículos orientadas a SEO, textos alternativos de imágenes, metadatos SEO y elementos destacados de equipamiento a partir de los datos de vehículos importados.

Las funciones de IA utilizan la configuración gestionada de Google Gemini en ADP Car Market Hub. No se requiere selección de proveedor, selección de modelo ni introducción de clave API en el backend de WordPress. El aprovisionamiento de IA específico para el cliente lo realiza AD Promotion después de la instalación.

Cuándo usar este documento

Lea este documento si necesita:

Decidir si habilitar el AI Assistant para su sitio.
Comprender cómo interactúan la cola en segundo plano y la generación por importación con WP-Cron.
Auditar el modelo de seguridad en torno a la configuración gestionada de Gemini y los activadores de administración.

Descripción general

El AI Assistant está implementado en AS24CI\Ai_Assistant. Cuando está habilitado, puede:

Generar una descripción automáticamente como parte del flujo de importación (enganchado en as24ci_vehicle_imported).
Procesar una cola de generaciones pendientes en segundo plano a través de WP-Cron (as24ci_process_ai_queue).
Permitir a los editores generar o regenerar una descripción manualmente desde la pantalla de edición del vehículo, tanto a través de una acción AJAX como de una acción admin-post de un solo uso.

La característica es de suscripción voluntaria (opt-in): no hace nada hasta que as24ci_ai_assistant_enabled se establece en '1' y se aprovisiona la configuración gestionada de Gemini. El callback de cron se registra incondicionalmente para que cualquier tarea previamente programada de una configuración anterior aún pueda completarse.

Configuración de IA gestionada

El plugin utiliza una única configuración de IA gestionada expuesta por AS24CI\Ai_Config. Las constantes de clave/modelo de Gemini que antes estaban codificadas en Ai_Config han sido eliminadas; la clase es ahora una fina capa sobre AS24CI\Ai_Credential_Manager:

Ai_Config::get_effective_model() — devuelve el modelo Gemini de tiempo de ejecución fijo, siempre Ai_Credential_Manager::PRIMARY_MODEL (actualmente gemini-3.5-flash). Cualquier valor de modelo proporcionado por la API es solo metadato y nunca controla la selección en tiempo de ejecución.
Ai_Config::get_managed_gemini_api_key() — devuelve la clave Gemini del cliente obtenida del sobre de credenciales cifrado sincronizado de servidor a servidor desde la API Platform. Devuelve una cadena vacía cuando la IA no puede ejecutarse (sin derecho de licencia ai_allowed o sin credencial almacenada). Nunca se expone en la interfaz de administración, diagnósticos, logs o cualquier superficie visible para el usuario.
Ai_Config::is_configured() — devuelve true solo cuando está disponible una clave Gemini gestionada utilizable.

Los ayudantes heredados de Ai_Assistant (get_api_key_for_provider(), get_model(), etc.) se conservan por compatibilidad con versiones anteriores y se resuelven en los valores gestionados de Gemini. No hay interruptor de proveedor, ni campo de clave API por proveedor, ni selector de modelo en el backend de WordPress.

Los idiomas de salida disponibles (de, en, fr, it), los tonos (professional, emotional, technical) y las longitudes objetivo (short, medium, long) se definen como constantes de clase en Ai_Assistant.

Cola en segundo plano

Gancho de cron: as24ci_process_ai_queue.
Programación personalizada: as24ci_every_5_minutes.
Tamaño de lote por ejecución: hasta 3 vehículos.
Intentos máximos por vehículo: 3.
Límite de extracto: 160 caracteres.

La cola permite al plugin distribuir la generación de IA a lo largo de las importaciones sin bloquear la solicitud del frontend que las originó.

Instrucciones paso a paso

Para habilitar y configurar el AI Assistant:

Abra la pestaña de administración del AI Assistant.
Active el ajuste Habilitar AI Assistant (as24ci_ai_assistant_enabled = '1').
Elija un idioma, tono, longitud objetivo y (opcionalmente) una plantilla de instrucción personalizada.
Decida si desea habilitar la opción Autogenerar al importar (as24ci_ai_assistant_auto_generate).
Guarde y ejecute una importación o active una única generación desde la pantalla de edición de un vehículo para verificar la conectividad.

La configuración gestionada de Gemini ya está establecida; no se presentan campos de proveedor, modelo o clave API en la interfaz de administración.

Generación manual

Existen dos rutas de administración:

AJAX (as24ci_generate_ai_assistant) — utilizado por la caja de metadatos (meta box) en la pantalla de edición del vehículo. Requiere la capacidad manage_as24_imports y el nonce as24ci_ai_generate.
Admin-post (as24ci_manual_ai_generate) — gestiona el botón manual de un solo uso Generar. Requiere el nonce por publicación as24ci_manual_ai_generate_<post_id> y la capacidad edit_post para el vehículo específico.

Ambos flujos finalmente llaman a la rutina gestionada de Gemini y escriben el resultado de vuelta en la publicación.

Activador de administración en segundo plano

El plugin expone la acción AJAX as24ci_trigger_ai_queue_now que procesa un lote de la cola de IA inmediatamente. Está protegida por manage_as24_imports y el nonce as24ci_trigger_ai_queue_now, y devuelve HTTP 400 si el AI Assistant está deshabilitado.

Referencia de configuración

Clave de opción	Propósito
`as24ci_ai_assistant_enabled`	Interruptor maestro. `'1'` habilita la característica.
`as24ci_ai_assistant_language`	Idioma de salida (`de`, `en`, `fr`, `it`).
`as24ci_ai_assistant_tone`	Tono de escritura (`professional`, `emotional`, `technical`).
`as24ci_ai_assistant_max_length`	Longitud objetivo (`short`, `medium`, `long`).
`as24ci_ai_assistant_auto_generate`	Generar durante el flujo de importación cuando `'1'`.
`as24ci_ai_assistant_custom_prompt`	Plantilla de instrucción (prompt) opcional.

Para obtener la lista completa de opciones del plugin, consulte Almacenamiento de opciones y ajustes.

Notas operativas

Flujo de datos de terceros: Cuando el AI Assistant está habilitado, los datos del vehículo y el contexto de la instrucción salen del servidor de WordPress y se envían al punto de conexión gestionado de Google Gemini. Revise el procesamiento de datos aplicable y los términos contractuales para la configuración de IA gestionada antes de habilitar las funciones de IA en producción.
Coste y cuota: El uso de la IA se realiza con cargo a la configuración gestionada de Gemini aprovisionada por AD Promotion. El plugin no expone precios por llamada.
Límites de tarifa: Gemini aplica límites de solicitudes y tokens de forma independiente al plugin. Las generaciones fallidas se reintentan hasta 3 veces por vehículo; los vehículos que fallan persistentemente se descartan para evitar bucles infinitos.
La autogeneración solo se activa en las importaciones cuando tanto el interruptor maestro como la opción Autogenerar están habilitados. La generación manual siempre funciona (independientemente de Autogenerar) cuando el interruptor maestro está encendido.
Gestión de claves gestionadas: la clave gestionada de Gemini se entrega de servidor a servidor mediante la API Platform y se mantiene cifrada por Ai_Credential_Manager. Nunca se escribe en wp_options en texto plano, ni se muestra en la interfaz de administración, ni se imprime en diagnósticos o logs.
Deshabilitar la característica detiene las nuevas generaciones, pero el gancho de cron registrado permanece para que las tareas ya en cola puedan completarse. Verifique que la cola esté vacía antes de confiar en que la característica está completamente desactivada.

Resolución de problemas

No se genera ninguna descripción al importar — confirme que as24ci_ai_assistant_enabled es '1', que Autogenerar está activado y que Ai_Config::is_configured() devuelve true (clave gestionada aprovisionada). Revise el log del plugin para ver las respuestas de error de Gemini.
El botón manual Generar no hace nada — revise la pestaña de red del navegador. Un código 403 indica que falta una capacidad o un nonce, un código 400 indica que el AI Assistant está deshabilitado.
La cola nunca se vacía — WP-Cron requiere tráfico regular en el sitio para activar los eventos programados. Configure una tarea cron externa o active la cola manualmente a través de la acción de administración Activar cola de IA ahora. Consulte Eventos de cron y programador.
El mismo vehículo nunca obtiene una descripción después de múltiples intentos — el contador de intentos por vehículo ha alcanzado 3. Investigue el error subyacente de Gemini en el log antes de restablecerlo.