insar-management-system-v2/docs/OLLAMA_DINSAR_DIAGNOSIS_DEPLOYMENT_20260620.md

Ollama D-InSAR Diagnosis Deployment

Last updated: 2026-06-20

This document is the current deployment contract for local Ollama integration in the D-InSAR analysis workflow.

Scope

• Ollama is used only for D-InSAR diagnosis and map/image interpretation tasks.
• The visible UI entry is InSAR形变分析 / D-InSAR / D-InSAR分析 / D-InSAR诊断.
• The standalone AI分析 first-level page is retired.
• Quality model training and batch quality prediction remain local backend tasks. They do not call Ollama.

Configuration

Set these values in the backend environment:

OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_API_URL=http://127.0.0.1:11434/api/generate
DEFAULT_VLM_MODEL=qwen3-vl:30b

The backend reads them through backend/app/config.py.

OLLAMA_BASE_URL must point to the server-local Ollama service. Do not point it to UNC or a workstation share. OLLAMA_API_URL should normally be ${OLLAMA_BASE_URL}/api/generate.

Model Selection

GET /ai/status checks ${OLLAMA_BASE_URL}/api/tags and returns:

• ollama_online
• ollama_models
• ollama_vlm_models
• ollama_base_url
• default_vlm_model

The D-InSAR diagnosis panel uses ollama_vlm_models for its model dropdown. ollama_models is the raw installed-model list and may include pure text models. If DEFAULT_VLM_MODEL is installed and classified as a vision model, it is selected. Otherwise the first detected vision model is selected.

The backend still has a fallback detector for compatibility. Preference order is:

1. User-selected model, if present in Ollama.
2. Model name containing qwen3-vl.
3. Model name containing qwen2-vl.
4. Model name containing minicpm-v.
5. Model name containing llama3.2-vision or llava.
6. Any model name containing vl, vision, or llava.
7. DEFAULT_VLM_MODEL.

Runtime Flow

1. User opens D-InSAR分析.
2. User selects D-InSAR诊断.
3. Frontend calls POST /ai/diagnosis.
4. Backend creates an AI_DIAGNOSIS task and job.
5. Job handler reads the registered D-InSAR preview image, injects spatial context and quality context into the prompt, then calls Ollama /api/generate.
6. The diagnosis report is written to ai_diagnosis.
7. The panel lists diagnosis records from GET /ai/diagnosis.

The older POST /ai/analyze-result/{result_id} and AI_ANALYZE task remain compatibility code. New UI should use POST /ai/diagnosis and AI_DIAGNOSIS.

Deployment Check

Run these checks on the server:

ollama list
curl http://127.0.0.1:11434/api/tags

Then check the system endpoint:

curl http://127.0.0.1:8000/api/ai/status

Expected result:

• ollama_online is true.
• ollama_vlm_models contains at least one vision-capable model.

Recommended model families for this project:

• qwen3-vl
• qwen2-vl
• minicpm-v
• llama3.2-vision
• llava

Avoid pure text models such as qwen2, llama3, mistral, or gemma for D-InSAR diagnosis.

Failure Handling

• If the panel shows Ollama offline, verify ollama serve is running and the configured port matches .env.
• If diagnosis stays queued or fails quickly, inspect the task log for AI_DIAGNOSIS.
• If the model dropdown is empty, /api/tags is unreachable or Ollama has no models installed.
• If a selected model fails at generation time, confirm the model supports image input.