ONLYOFFICE IA local con Ollama o vLLM: arquitectura, configuración y monitorización

ONLYOFFICE IA local: conecta Docs 10.0 a Ollama o vLLM, ajusta aiSettings y el relé /ai-proxy, y monitoriza TTFT y StatsD con OpenTelemetry.
ONLYOFFICE IA locale avec Ollama ou vLLM : architecture, configuration et supervision

En ONLYOFFICE, IA local significa resumir o traducir un documento sin que ni un byte salga de la red. Para el equipo de explotación es, sobre todo, un nuevo camino crítico: un editor web, un relé en el lado del servidor y un motor de inferencia en GPU. Cuando un usuario hace clic en «Resumir» y no llega nada, hay que saber cuál de los tres eslabones ha fallado.

Este artículo describe la arquitectura de ONLYOFFICE Docs 10.0 (la versión documentada en el momento de escribirlo) conectado a Ollama o vLLM, los parámetros del servidor que importan y después la monitorización de extremo a extremo. Todos los parámetros citados proceden de la documentación de ONLYOFFICE, vLLM y Ollama. Por el lado de Dynatrace, el método vale tanto para Dynatrace SaaS como para Dynatrace Managed: solo cambia la dirección OTLP.

Si partes de cero con los modelos locales, empieza por instalar y monitorizar Ollama o por vLLM en producción; aquí se da por supuesto que el motor ya está en marcha.

Arquitectura: ONLYOFFICE IA local en tres eslabones

Las funciones de IA de ONLYOFFICE viven en un plugin, llamado AI Tools en el registro de cambios de la versión 10.0. El plugin se ejecuta en el editor, es decir, en el navegador del usuario. Puede llegar al modelo de dos maneras:

  • directamente desde el navegador: la petición sale del puesto hacia Ollama. Para este caso la documentación pide ajustar OLLAMA_ORIGINS (cabeceras CORS);
  • mediante el relé /ai-proxy del servidor Docs: la documentación de configuración del servidor describe este punto de entrada, su plazo (aiSettings.timeout) y el hecho de que las peticiones salientes pasan por el filtrado externalRequest.

La elección lo cambia todo para la monitorización. En modo directo, el servidor Docs no ve pasar nada y cada puesto debe poder llegar al motor. Con el relé, el servidor Docs se convierte en un único punto de paso: ahí se leen los errores, ahí se aplica el filtrado, y el motor solo necesita ser accesible desde el servidor.

Ollama y vLLM no se conectan de la misma manera. Ollama figura en la lista de proveedores del plugin: se introduce una URL base (http://localhost:11434 en la guía oficial) en lugar de una clave de API. vLLM expone una API compatible con OpenAI bajo /v1; la documentación de ONLYOFFICE no cita vLLM, pero describe cómo añadir un proveedor personalizado mediante un archivo JavaScript que extiende AI.Provider con una URL, una clave opcional y un sufijo como v1. Esa es la vía que hay que probar para vLLM.

Los parámetros del servidor que conviene conocer

ONLYOFFICE Docs lee su configuración con node-config en /etc/onlyoffice/documentserver/ en Linux. No modifiques default.json: coloca tus valores en local.json, que lo sobrescribe. Cuatro bloques afectan a la IA y a su monitorización.

Extractos de la documentación ONLYOFFICE Server configuration: bloque statsd con useMetrics false, puerto 8125 y prefijo ds., bloque aiSettings con enable, timeout 5m, allowedCorsOrigins y allowBrowserProxy, bloque externalRequest.action con blockPrivateIP true
  • aiSettings.enable (true por defecto): con false, el plugin se elimina de /plugins.json y las peticiones a /ai-proxy reciben un HTTP 403. Es el interruptor de emergencia.
  • aiSettings.timeout ("5m"): plazo del relé. Un modelo lento en CPU puede alcanzarlo.
  • aiSettings.allowBrowserProxy (true): el relé transmite también una petición cuyo destino no corresponde a ningún proveedor configurado, por ejemplo un servidor MCP declarado en el navegador. El servidor no añade ninguna credencial, exige un token de sesión válido y solo acepta destinos http o https absolutos. Con false, esas peticiones reciben un 403.
  • externalRequest.action.blockPrivateIP (true): las direcciones IP privadas están bloqueadas. Un motor situado en 10.x o 192.168.x puede, por tanto, ser rechazado por el relé. Flexibilizarlo es una decisión de seguridad, que se toma con el equipo de redes.
  • statsd.useMetrics (false), statsd.host, statsd.port ("8125"), statsd.prefix ("ds."): la exportación de métricas del servidor Docs.

El parámetro de integración editorConfig.customization.ai.disabled, añadido en la 10.0, desactiva la IA para una apertura de documento concreta. Las claves y los ajustes de los modelos también pueden introducirse en la página /info del servidor desde la versión 9.0.

En la práctica: conectar y verificar

Paso 1: abrir Ollama al editor

Si el plugin llama a Ollama desde el navegador, Ollama debe devolver las cabeceras CORS correctas. La documentación de ONLYOFFICE da el procedimiento con systemd y el comando de verificación:

Comandos de la documentación ONLYOFFICE Configuring Ollama with CORS: systemctl edit ollama con OLLAMA_ORIGINS, reinicio, y después una petición OPTIONS a /api/tags y la respuesta esperada 204 con las cabeceras Access-Control-Allow

Los comodines http://* y https://* sirven para un puesto de pruebas, no para un servidor compartido: la misma página recomienda enumerar orígenes explícitos en producción. Por defecto Ollama solo escucha en localhost; abrirlo a la red (OLLAMA_HOST=0.0.0.0) exige, según la documentación, un reverse proxy con TLS y autenticación.

Paso 2: arrancar vLLM con una clave

vllm serve NousResearch/Meta-Llama-3-8B-Instruct \
  --dtype auto \
  --api-key token-abc123

curl http://localhost:8000/v1/models -H "Authorization: Bearer token-abc123"

vLLM escucha por defecto en http://localhost:8000. Atención: la documentación precisa que --api-key (o VLLM_API_KEY) solo protege las rutas /v1, /v2 y /inference; /invocations sigue abierta. Coloca vLLM detrás de un reverse proxy y no expongas nunca el puerto directamente a los puestos.

Paso 3: restringir y ajustar el relé

{
  "aiSettings": {
    "timeout": "2m",
    "allowBrowserProxy": false
  },
  "statsd": {
    "useMetrics": true,
    "host": "localhost",
    "port": "8125",
    "prefix": "ds."
  }
}

Este local.json acorta el plazo (un fallo rápido es mejor que un usuario esperando cinco minutos), corta el relé hacia destinos no declarados y activa StatsD. Desactivar allowBrowserProxy desactiva también los destinos configurados en el navegador, como un servidor MCP: comprueba que nadie los use. Reinicia los servicios de Docs tras la modificación.

Paso 4: verificar cada eslabón

# Serveur Docs : bases, broker, Redis et stockage (réponse attendue : true)
curl -s https://docs.example.com/healthcheck

# Ollama : modèles disponibles
curl -s http://localhost:11434/api/tags

# vLLM : métriques Prometheus
curl -s http://localhost:8000/metrics | grep vllm:time_to_first_token_seconds

El control /healthcheck verifica, según la documentación, las bases de datos, el broker de mensajes, Redis y el almacenamiento; no prueba el motor de IA. Hace falta, por tanto, una sonda propia para el motor.

Monitorizar la cadena con OpenTelemetry y Dynatrace

Un solo OpenTelemetry Collector puede recoger las dos fuentes: el receptor statsd de la distribución contrib (estabilidad beta, escucha por defecto en localhost:8125 por UDP) para ONLYOFFICE, y el receptor prometheus para vLLM. Los componentes y el formato de exportación se detallan en los componentes del Collector contrib.

receivers:
  statsd:
    endpoint: localhost:8125
  prometheus:
    config:
      scrape_configs:
        - job_name: vllm
          static_configs:
            - targets: ["localhost:8000"]
exporters:
  otlphttp:
    endpoint: https://<env-id>.live.dynatrace.com/api/v2/otlp   # SaaS
    # Managed : https://<votre-domaine>/e/<env-id>/api/v2/otlp
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"
service:
  pipelines:
    metrics:
      receivers: [statsd, prometheus]
      exporters: [otlphttp]

El token debe llevar el scope metrics.ingest. Por el lado de vLLM, tres métricas bastan para un primer dashboard: vllm:time_to_first_token_seconds, vllm:e2e_request_latency_seconds y vllm:num_requests_waiting. El esquema de la documentación de diseño de vLLM muestra lo que mide cada una:

Esquema de la documentación de vLLM sobre los intervalos de una petición: cola de espera, prefill y después decode en el Engine Core, TTFT medido en el API Server y latencia entre tokens ITL
Source : github.com

El TTFT es lo que el usuario percibe en el editor: el retardo hasta que el texto empieza a aparecer. Un aumento de la cola (num_requests_waiting) con un TTFT que sube indica una GPU saturada, no una avería de ONLYOFFICE. Para Ollama, que no expone esos histogramas, una sonda sintética sobre /api/generate devuelve total_duration, eval_count y eval_duration, en nanosegundos.

Un SLO legible para el soporte

Formula el objetivo desde el punto de vista del usuario: «el 95 % de las solicitudes de resumen produce una primera palabra en menos de 3 segundos en 28 días». El umbral es un ejemplo que hay que calibrar con tu hardware. El TTFT de vLLM sirve de SLI; el 403 de /ai-proxy y el /healthcheck sirven para el diagnóstico. Con estas tres señales, la guardia (on-call) sabe en un minuto si el problema viene de la red, del servidor Docs o del motor, lo que reduce el MTTR.

Buenas prácticas

  • Prefiere el relé /ai-proxy al acceso directo: un único camino de red, un único punto de filtrado.
  • Mantén activo blockPrivateIP mientras un análisis de red no justifique una excepción.
  • Reduce aiSettings.timeout para fallar rápido en lugar de bloquear el editor.
  • No cuentes solo con --api-key en vLLM: reverse proxy obligatorio.
  • Documenta el interruptor aiSettings.enable en el runbook de incidentes.
  • Monitoriza el motor por separado: /healthcheck no lo cubre.

Preguntas frecuentes

¿Funciona ONLYOFFICE IA local con la versión web?

La página actual sobre el agente del plugin trata Ollama y LM Studio como proveedores locales que se introducen por URL, sin distinguir entre escritorio y web. Una guía antigua reservaba Ollama a los Desktop Editors: prueba con tu versión antes de anunciarlo a los usuarios.

¿Se puede conectar vLLM sin un proveedor personalizado?

La documentación de ONLYOFFICE no cita vLLM. El proveedor personalizado (archivo JavaScript que extiende AI.Provider) es la vía documentada para una API compatible con OpenAI.

¿Envía el servidor Docs trazas?

La configuración documenta una exportación StatsD, no trazas de OpenTelemetry. Las trazas de extremo a extremo se construyen en el lado del motor o con una sonda sintética.

Conclusión

Una IA local en ONLYOFFICE mantiene los documentos en tu casa, pero añade un motor de inferencia al camino crítico de la ofimática. Elige el relé del servidor, conserva los filtros por defecto, acorta el plazo y sigue el TTFT como indicador principal. Para situar este componente en el conjunto, consulta la stack de IA de código abierto autoalojada y, para los destinos MCP del relé, proteger un servidor MCP. Referencias: configuración del servidor ONLYOFFICE Docs y configuración de Ollama con CORS.

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a los proyectos citados. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba los comandos y las opciones en su documentación oficial.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Ghidra MCP : brancher un agent IA sur des outils locaux, isolation et traçabilité des appels

Ghidra MCP: conectar un agente de IA a herramientas locales, con aislamiento y trazabilidad de las llamadas

Next Post
MCP grand public : ce que Google Home MCP apprend aux SRE sur l'authentification, les permissions et l'audit des agents

MCP para el gran público: lo que Google Home MCP enseña a los SRE sobre autenticación, permisos y auditoría de agentes

Related Posts