Refactor local InSAR asset and production workflows

2026-06-21 12:30:21 +08:00
parent 65a8cc4eac
commit 71c524967c
88 changed files with 11165 additions and 3017 deletions
@@ -0,0 +1,97 @@
+# 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:
+
+```env
+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:
+
+```powershell
+ollama list
+curl http://127.0.0.1:11434/api/tags
+```
+
+Then check the system endpoint:
+
+```powershell
+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.