Asistente de IA

El asistente de IA es un panel de “converse con sus datos” que convierte peticiones en lenguaje natural en operaciones propias de Meratyn — SQL espacial, estilizado de capas, control del mapa y más — y las aplica a través de la aplicación, igual que lo haría a mano. Ábralo desde Procesamiento → AI Assistant (parte superior del menú) o desde la paleta de comandos. Se acopla como un panel redimensionable en la parte inferior de la ventana (arrastre su borde superior para cambiar el tamaño, ✕ para cerrar).

Como el asistente actúa a través del store en lugar de manipular el mapa directamente, los cambios de proyecto creados por el usuario y registrados por Travels se pueden deshacer con Ctrl/Cmd + Z. Los efectos secundarios del host, los plugins y el fallback de MapLibre quedan fuera de ese historial. Cada llamada a herramientas (incluido el SQL que genera) se muestra en la transcripción para que pueda ver exactamente qué se ejecutó.

El asistente es opcional y permanece desactivado hasta que configure un proveedor o hasta que el operador del despliegue active el proxy de IA gestionado. Meratyn mantiene los datos del proyecto en local de forma predeterminada; al enviar un mensaje, el texto y su contexto acotado se envían al proveedor o proxy gestionado que haya configurado.

Configuración: elegir un proveedor de IA

El asistente funciona sobre el runtime TanStack AI, enteramente dentro de la aplicación: sus mensajes y datos van directamente desde su dispositivo al proveedor que configure, sin servidores de Meratyn de por medio. Configure uno o más proveedores en Configuración → AI Providers:

• Ollama ejecuta modelos en su propia máquina — sin clave de API y nada sale de su equipo. Apunte OLLAMA_BASE_URL a su host de Ollama (el sufijo /v1 se añade automáticamente); fije OLLAMA_MODEL para elegir qué modelo descargado usar. En la aplicación de escritorio el host puede ser cualquier máquina de su red local (por ejemplo http://192.168.1.20:11434) — no hace falta escribir http://.
• Personalizado cubre cualquier endpoint compatible con OpenAI — LiteLLM, vLLM, OpenRouter, Groq, Together, un servidor local, etc. — mediante su API chat-completions.
• Cada perfil tiene un botón Probar conexión que sondea el endpoint y, si falla, le indica la solución exacta — para Ollama, el valor exacto de OLLAMA_ORIGINS; para una app web HTTPS frente a un servidor HTTP plano, la explicación del contenido mixto.

Las claves alojadas (y las credenciales AWS) se usan directamente desde su navegador para llamar al proveedor; nunca se envían a los servidores de Meratyn. Al guardar la configuración se habilita el panel inmediatamente — sin necesidad de recargar.

Usar Ollama local desde la aplicación web

La aplicación web alojada de Meratyn se conecta directamente desde su navegador con Ollama en su equipo. Los avisos y las respuestas no pasan por un servidor de Meratyn. Como las peticiones del navegador incluyen el origen de la página, Ollama debe permitir explícitamente https://mappview.mapptech.com.co.

Defina esta variable para el servidor de Ollama y reinícielo:

OLLAMA_ORIGINS=https://mappview.mapptech.com.co

Mantenga esta URL base de Ollama en Configuración → Proveedores de IA → Ollama:

http://localhost:11434

Configure OLLAMA_ORIGINS según su sistema operativo:

Linux (systemd)

Ejecute sudo systemctl edit ollama.service y añada:

[Service]
Environment="OLLAMA_ORIGINS=https://mappview.mapptech.com.co"

Después recargue y reinicie el servicio:

sudo systemctl daemon-reload
sudo systemctl restart ollama

macOS

Defina la variable para la aplicación Ollama, cierre Ollama y vuelva a abrirlo:

launchctl setenv OLLAMA_ORIGINS "https://mappview.mapptech.com.co"

Windows

Cierre Ollama, cree una variable de entorno de usuario llamada OLLAMA_ORIGINS con el valor https://mappview.mapptech.com.co y vuelva a iniciar Ollama.

Docker

Pase el origen permitido al iniciar el contenedor:

docker run -d \
  -e OLLAMA_ORIGINS=https://mappview.mapptech.com.co \
  -p 11434:11434 \
  ollama/ollama

Para una URL de Meratyn autoalojada, sustituya el valor por el origen exacto que aparece en el error de Ollama, incluido el esquema y el puerto (por ejemplo, http://192.168.1.98:4000). Es un permiso del servidor Ollama y una página web no puede activarlo automáticamente. Consulte la guía oficial de Ollama sobre orígenes web.

IA gestionada en un despliegue Docker protegido con contraseña

Un operador del despliegue puede proporcionar IA sin distribuir claves de API de proveedores. En esta configuración, el navegador llama a la ruta /ai del mismo origen. El nginx de Docker comprueba el usuario y la contraseña de HTTP Basic Auth de la instancia cuando el operador los ha configurado, y después añade un token de instancia exclusivo del servidor y reenvía la solicitud al proxy de IA configurado. El navegador no recibe ni el token de instancia ni el token de Cloudflare AI Gateway.

Los usuarios solo necesitan iniciar sesión en la instancia Meratyn; no configuran una clave de proveedor de IA. Las solicitudes enviadas directamente al proxy configurado sin el token exclusivo del servidor reciben 401 Unauthorized.

El operador debe arrancar el contenedor con todas las variables de IA gestionada:

docker run --rm -p 8080:80 \
  -e MAPPVIEW_AUTH_USER=admin \
  -e MAPPVIEW_AUTH_PASSWORD='change-me' \
  -e MAPPVIEW_AI_URL=/ai \
  -e MAPPVIEW_AI_MODEL=openai/gpt-5.6-luna \
  -e MAPPVIEW_AI_PROXY_URL=http://host.docker.internal:8791 \
  -e MAPPVIEW_AI_PROXY_TOKEN="$MAPPVIEW_AI_PROXY_TOKEN" \
  mapptech/mappview:local

Si MAPPVIEW_AI_URL no está definida, el entrypoint de Docker deja el proxy gestionado desactivado y no inyecta ninguna URL de proxy de IA en la aplicación.

Variables opcionales:

Cuando hay más de una clave de proveedor configurada, aparece un desplegable de proveedor en el encabezado del panel; un desplegable de modelo permite cambiar de modelo para el proveedor seleccionado. Su elección se recuerda entre sesiones.

Leer claves del entorno de su sistema (escritorio)

En la aplicación de escritorio, Meratyn también lee las claves del asistente directamente de las variables de entorno de su sistema operativo — las que exporta desde su perfil de shell o define en el cuadro de diálogo Variables de entorno de Windows. Defina una variable compatible en el entorno de su SO, reinicie la aplicación, y el proveedor correspondiente queda configurado automáticamente: nunca teclea la clave en Configuración y, como no se introduce allí, nunca se escribe en el archivo de proyecto .meratyn.json guardado. Esta es la forma recomendada de mantener las claves de API fuera de los archivos de proyecto que comparte o confirma en git.

Solo se leen de su entorno los siguientes nombres de lista blanca — Meratyn nunca lee ninguna otra variable del sistema (su PATH, HOME, etc., nunca llegan a la aplicación), y esta lista blanca se aplica en el backend nativo, no solo en la interfaz:

Precedencia: un valor introducido en Configuración → Environment Variables siempre gana; el entorno del SO solo rellena los huecos. En la configuración de IA, cualquier campo suministrado por el entorno muestra una nota nombrando la variable que lo respalda — deje ese campo vacío para seguir usando el valor del entorno.

Las credenciales genéricas de la nube nunca se leen Variables como AWS_ACCESS_KEY_ID (y el OLLAMA_HOST ambiental) están deliberadamente excluidas de la lectura del entorno del SO: los desarrolladores suelen tener credenciales AWS exportadas en su shell para trabajo no relacionado, y Meratyn nunca debe adoptarlas silenciosamente como credenciales de LLM.

Solo escritorio Leer variables de entorno del SO requiere el backend nativo, así que se aplica solo a la aplicación de escritorio. Las builds de navegador y Jupyter no pueden leer el entorno del sistema; allí, introduzca las claves en Configuración → Environment Variables (u hornéelas en tiempo de build). Los cambios en las variables del SO se recogen en el siguiente arranque de la aplicación.

Uso

Escriba una petición y pulse Enter (o haga clic en Send); Shift + Enter inserta una nueva línea y Ctrl/Cmd + Enter también envía. El asistente transmite su respuesta en streaming, ejecuta herramientas según sea necesario e informa de lo que hizo. Mientras trabaja, Send pasa a ser Stop — haga clic para cancelar. Clear (el icono de goma de borrar) inicia una conversación nueva.

Su conversación se recuerda: se guarda en este dispositivo por proyecto y se restaura al reabrir el panel o la aplicación, y cambiar de proveedor o modelo conserva el historial. Clear es lo que realmente empieza de cero. Solo se conservan las conversaciones más recientes, para que el almacenamiento permanezca acotado.

show me all parcels larger than 1 hectare within 500 m of a river
color the counties by population using a graduated red ramp
buffer the roads by 100 m, then clip them to the county boundary
load the latest Sentinel-2 scene over this view
zoom to Africa, then switch to a dark basemap
add an OpenTopoMap basemap

Qué puede hacer

El asistente funciona llamando a un conjunto fijo de herramientas — no puede inventar operaciones, así que sus acciones se mantienen dentro de la superficie validada de Meratyn.

Búsqueda de noticias de desastres

Para consultas auditadas sobre desastres y noticias de emergencias, configure la ruta gestionada /v1/disaster-news mediante el proxy inverso /ai existente (configurado con MAPPVIEW_AI_PROXY_BASE_URL). El servicio edge conserva la clave del operador de Tavily; nunca se envía al navegador, al archivo de proyecto ni a errores serializables. La ruta fija el tema news, la profundidad basic, una petición por consulta, ningún cuerpo de artículo sin procesar y como máximo seis resúmenes. Solo acepta una consulta recortada de hasta 512 caracteres, limita el cuerpo a 2 KiB, agota el tiempo tras 25 segundos y aplica el límite del servicio edge (10 peticiones por cliente y minuto de forma predeterminada; el operador puede reducirlo). Los resultados se limitan a URL HTTP(S) sin credenciales y los fragmentos se recortan antes de devolverse. Si la ruta no está disponible o no está configurada, Meratyn informa un fallo seguro; esta ruta auditada no recurre a un proveedor sin límites.

Prompts de ejemplo

Los prompts son de forma libre — estos son puntos de partida, no comandos fijos. Refiérase a las capas por nombre; el asistente averigua el resto. También puede encadenar pasos en un solo mensaje (“buffer the roads by 100 m and then clip to the county boundary”) o seguir refinando entre turnos (“now color it by area”).

Explorar y consultar

what layers are loaded, and what fields does the parcels layer have?
how many parcels are larger than 1 hectare?
list the 10 most populous counties with their population
show parcels within 500 m of a river and add them as a layer
count points in each polygon of the districts layer

Geoprocesamiento y análisis

buffer the roads by 100 meters
buffer the roads by 100 m, then clip the buffer to the county boundary
dissolve the parcels by zoning type
find where the floodplain overlaps the buildings (intersection)
create an H3 hex grid at resolution 8 over the points and count points per cell
compute centroids of the counties and add them as a layer

Simbología

color the counties by population with a graduated red ramp
style the parcels categorized by land-use type
shade the tracts by median income using a viridis ramp with 7 classes

Añadir datos e imágenes

load the latest Sentinel-2 scene over this view
add the most recent cloud-free Landsat image for this area
search the Planetary Computer for NAIP imagery here
add an OpenTopoMap basemap
add this GeoJSON: https://example.com/data.geojson

Control del mapa y estilizado

zoom to the parcels layer
fly to Medellín
switch to a dark basemap
hide the buildings layer and set the parcels opacity to 0.5
remove the temporary buffer layer

Avanzado (alternativa con código)

switch the map to a 3D globe projection
enable terrain with hillshade exaggeration of 1.5
load a CSV from a URL with pandas and summarize its columns

Seguridad y privacidad

• Actúa a través del store. Las acciones sobre capas, estilo, mapa base y adición/eliminación pasan por el mismo flujo de datos unidireccional que el resto de la aplicación, así que se reconcilian de forma consistente y quedan cubiertas por deshacer/rehacer.
• Auditable. El SQL generado y cada llamada a herramientas aparecen en la transcripción.
• SQL de solo lectura. La herramienta run_sql rechaza cualquier cosa que no sea una consulta SELECT / WITH.
• Contexto acotado. Solo los nombres de capas/tablas, los nombres de campos de atributos y la vista actual se envían al modelo — no los datos de sus geometrías.
• Lo que sale de su navegador. Cuando envía un prompt, este (más ese contexto acotado) se envía a su proveedor LLM elegido usando su propia clave. No habilite el asistente sobre datos sensibles que no pueda compartir con ese proveedor.

Advertencia sobre la ejecución de código Las alternativas JavaScript y Python ejecutan código generado por el modelo dentro de la aplicación para cubrir peticiones que ninguna herramienta dedicada atiende. Sus cambios directos sobre el mapa omiten el store y no son deshacibles. El código se muestra en la transcripción.

Limitaciones

• Requiere una clave de API de un proveedor; no se soporta el uso sin conexión.
• Sujeto al coste y límites de tasa de cada proveedor y a la política CORS/CSP de su red (llamadas del lado del navegador).
• Los endpoints de teselas no oficiales de Google Maps están deliberadamente excluidos; use los mapas base oficialmente soportados listados o suministre su propia URL XYZ.