Saltar al contenido principal

Chatbot

docStatic puede añadir a tu sitio web un chatbot con IA que responda a preguntas sobre tu documentación. Por defecto, se ejecuta íntegramente en el navegador del visitante utilizando WebLLM (a través de WebGPU), por lo que no se necesita ningún servicio externo, clave API ni servidor. Este mismo widget también puede redirigirse a un proveedor de pago que alojes tú mismo, sin cambiar nada de lo que ven los visitantes.

La función está desactivada por defecto en dos niveles, por lo que nunca afecta a los tiempos de carga de las páginas a menos que se desee realmente:

  • Nivel del sitio: un interruptor principal en la configuración del chatbot. Desactivado por defecto; cuando está desactivado, no se envía ningún código del chatbot a los visitantes.
  • Nivel del visitante: incluso cuando está activado en todo el sitio, cada visitante solo ve un botón de inicio oculto. No se descarga nada hasta que hagan clic en él de forma explícita.
Requisitos de WebGPU

WebLLM requiere que el navegador del visitante sea compatible con WebGPU. Actualmente, solo se sabe que funciona de forma fiable en Safari y en los navegadores basados en Chromium (Chrome, Opera) en ordenadores de sobremesa. Los visitantes que utilicen navegadores no compatibles verán un mensaje de error al intentar activar el asistente; si necesitas un alcance más amplio, plantéate utilizar la opción de la API remota.

Activación del chatbot​

Abre la configuración del chatbot en el CMS y activa Habilitar chatbot. Elige un proveedor de IA:

  • WebLLM (en el navegador, gratuito): la opción predeterminada. No se requiere ninguna configuración más allá de la elección opcional de un modelo.
  • API remota (proxy alojado por el desarrollador): reenvía las solicitudes a un backend que tú controlas, tal y como se describe a continuación.
Respuestas basadas en tu documentación

Cuando el sitio se ha creado con su índice de búsqueda local predeterminado disponible, el chatbot recupera las secciones más relevantes de tu documentación y las incluye como contexto antes de responder, de modo que las respuestas citan páginas reales en lugar de hacer conjeturas. Este contexto no está disponible en el entorno de desarrollo local, sino solo tras una compilación completa en producción.

Elección de un modelo WebLLM​

El modelo predeterminado es Qwen2.5-1.5B-Instruct-q4f16_1-MLC (aproximadamente 1,6 GB, almacenado en la caché del navegador tras la primera descarga), elegido por su amplia cobertura multilingüe: más de 29 idiomas, incluidas todas las configuraciones regionales que este sitio ofrece de forma predeterminada. Puedes cambiarlo en el campo Configuración de WebLLM utilizando cualquier ID de modelo precompilado de WebLLM:

  • SmolLM2-360M-Instruct-q4f16_1-MLC: mucho más pequeño y rápido, pero solo en inglés.
  • Llama-3.2-1B-Instruct-q4f16_1-MLC: más pequeño que el predeterminado y cubre inglés, alemán, francés, italiano, portugués, hindi, español y tailandés, pero no japonés ni otros idiomas que no utilicen el alfabeto latino.
Comprueba la cobertura de idiomas antes de cambiar de modelo

Si tu sitio web ofrece un idioma que un modelo más pequeño no admite oficialmente, es posible que las respuestas en ese idioma no sean fiables, incluso aunque el chatbot ya envíe automáticamente la instrucción «responder en este idioma». Comprueba los idiomas que admite un modelo antes de establecerlo como predeterminado.

Varios idiomas​

El chatbot se adapta automáticamente a la configuración regional en la que el visitante esté navegando en ese momento; no hay que configurar nada más allá de traducir el texto del CMS (a continuación):

  • El idioma de respuesta del modelo. El chatbot indica al modelo en qué idioma debe responder, basándose en la configuración regional de la página y en su nombre de visualización configurado (a partir de los ajustes de idioma del sitio), por lo que no es necesario seleccionar el idioma para cada pregunta.
  • Contexto de la documentación recuperada. Cada configuración regional tiene su propio índice de búsqueda, creado a partir de las páginas traducidas de esa configuración regional, por lo que las referencias apuntan automáticamente al contenido del idioma correcto.
  • El texto de la interfaz del propio widget de chat (botones, mensajes de estado) se traduce mediante el mecanismo estándar de traducción de componentes de docStatic, el mismo que se utiliza en el resto de este sitio web.

El texto redactado por el administrador —la etiqueta del botón de inicio, el mensaje de bienvenida y las indicaciones del sistema enviadas a cada proveedor— se encuentra en el CMS, en la sección Chatbot, como una entrada de traducción por idioma. Una configuración regional que no tenga su propia entrada recurre al texto predeterminado (en inglés).

Conexión de un proveedor de pago​

Dado que los sitios de docStatic son estáticos y no tienen un backend propio, el chatbot nunca incrusta una clave API del proveedor en el propio sitio. Hacerlo la expondría a todos los visitantes. En su lugar, al cambiar Proveedor de IA a API remota, el widget apunta a una URL de punto final que tú alojas y controlas. Tu punto final almacena la clave de API real en el lado del servidor y normaliza la respuesta del proveedor a un pequeño formato de transmisión que el widget entiende: una serie de eventos data: {"delta": "...", "done": false}, que terminan con data: [DONE].

El ejemplo que aparece a continuación es solo una implementación de referencia. No lo implementa docStatic y debe alojarse por separado (por ejemplo, como un Cloudflare Worker o una función de Netlify) y configurarse con tu propia clave de API como secreto.

<Tabs> <TabItem value="cloudflare" label="Cloudflare Worker">

export default {
  async fetch(request, env) {
    const { messages } = await request.json();

    const upstream = await fetch("https://api.anthropic.com/v1/messages", {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-api-key": env.ANTHROPIC_API_KEY,
        "anthropic-version": "2023-06-01",
      },
      body: JSON.stringify({
        model: "claude-3-5-haiku-latest",
        max_tokens: 1024,
        stream: true,
        messages,
      }),
    });

    // Anthropic already streams as SSE; forward it as-is.
    return new Response(upstream.body, {
      headers: { "content-type": "text/event-stream" },
    });
  },
};

</TabItem> <TabItem value="netlify" label="Netlify Function">

export default async (request) => {
  const { messages } = await request.json();

  const upstream = await fetch("https://api.anthropic.com/v1/messages", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": process.env.ANTHROPIC_API_KEY,
      "anthropic-version": "2023-06-01",
    },
    body: JSON.stringify({
      model: "claude-3-5-haiku-latest",
      max_tokens: 1024,
      stream: true,
      messages,
    }),
  });

  return new Response(upstream.body, {
    headers: { "content-type": "text/event-stream" },
  });
};

</TabItem> </Tabs>

Nunca incrustes una clave compartida en el lado del cliente

No introduzcas una clave API real en el campo «URL del punto final» de la configuración del chatbot, ni en ningún otro lugar que forme parte del sitio web generado. El punto final que configures debe ser un backend propio, y la clave debe guardarse como un secreto del lado del servidor.