版本 1.0.1 · 更新时间 2026-11-17 · 本文档由当前仓库代码逐文件核对撰写;深度设计文档见 后端.md,全链路实现拆解见 整体实现.md
焰哨后端是基于 FastAPI + LangGraph 构建的森林火险智能分析与预警服务。它以云南 16 州市、5411 条历史火点 与 GTWR 预测火险数据为底座,通过 六个协作智能体(编排、数据、GIS、RAG、报告、评审)组成的多智能体流水线,把一次自然语言指令变成「意图解析 → 并行取证 → 知识增强 → GIS 叠加 → 报告生成 → 自动评审 → 人工审批」的完整闭环,全程 SSE 流式推送,支持 HITL 人工审批闸口 与 Postgres 检查点断点续跑。
- 功能地图
- 总体架构
- 多智能体工作流
- 一次任务的完整时序
- 技术栈
- 目录结构
- 快速开始
- 环境变量
- API 总览(58 个端点)
- LLM 多供应商接入
- RAG 知识库检索
- 视觉与语音
- 数据模型
- 安全设计
- 可观测性
- 测试与脚本
- 部署
- 相关文档
| 模块 | 入口路由 | 能力(实现位置) |
|---|---|---|
| 智能查询 | /api/v1/query |
自然语言 → LLM 意图解析(history/predict/summary 三类)→ 参数化 SQL → 结构化结果 + 文字解读,历史按用户隔离去重回显(app/services/query_service.py) |
| 多智能体协作 | /api/v1/agent |
LangGraph 八节点 StateGraph 流水线,SSE 逐步推送思考流与报告正文,评审三态循环 ≤2 轮,HITL 审批三动作,Postgres 检查点断点续跑(app/agents/orchestrator_agent.py) |
| RAG 知识库 | /api/v1/rag |
文档上传(txt/md/docx/pdf)→ OCR 兜底链 → 500/50 分块 → 百炼向量化 → pgvector 检索 → rerank 精排(失败降级 RRF)→ 流式问答(app/services/rag_service.py) |
| 报告中心 | /api/v1/reports |
报告列表 / 详情 / 导出(md、html)/ 删除 / 独立生成,按用户隔离(app/api/v1/routes/report.py) |
| 火情视觉识别 | /api/v1/vision |
上传图片 → qwen-vl 系列视觉模型识别火情 → 识别历史管理 → 原图回看(app/api/v1/routes/media.py) |
| 语音能力 | /api/v1/vision |
TTS 语音合成(qwen3-tts-flash)+ ASR 语音识别(qwen3-asr-flash),供应商可切换 aliyun/amd |
| GIS 数据服务 | /api/v1/dashboard |
历史火点 / 预测火险 / 区域边界 / 应急资源四类 GeoJSON 供前端地图渲染,大屏汇总统计(app/services/data_service.py) |
| 系统管理 | /api/v1/admin |
系统状态体检、模型能力矩阵与熔断器视图、运行时配置热更新(密钥脱敏回显)、连接测试、日志、用户管理、百炼模型目录与配额(app/api/v1/routes/admin.py) |
| 认证与会话 | /api/v1/auth |
注册 / 登录(节流防护)/ 登出(token_version 吊销)/ 资料修改 / 改密(app/core/security.py、app/core/session.py、app/core/ratelimit.py) |
系统分五层:路由层(薄壳)、编排层(LangGraph + Agent)、服务层(业务逻辑)、数据层(ORM + 仓储)、横切层(配置/LLM/安全/观测)。所有 LLM 调用必须经统一调用层 llm_invoker,熔断与降级才能全局生效。
flowchart TB
FE["前端 Vue 3 + OpenLayers<br/>fire_agent_front"] -->|"HTTP / SSE"| NGINX["Nginx 反代<br/>/api 转发 · SSE 关缓冲<br/>/tianditu 去Referer"]
NGINX --> API["FastAPI app/main.py<br/>:8000"]
subgraph L1["路由层 · app/api/v1/routes/ · 8 组薄壳"]
R1[auth] --- R2[dashboard] --- R3[query] --- R4[rag]
R5[agent] --- R6[reports] --- R7[vision/media] --- R8[admin]
end
subgraph L2["编排层"]
ORCH["OrchestratorAgent<br/>LangGraph StateGraph<br/>app/agents/orchestrator_agent.py"]
A1[DataAgent] --- A2[GisAgent] --- A3[RagAgent] --- A4[ReportAgent] --- A5[ReviewAgent]
WF["app/workflows/agent_workflow.py<br/>流式执行 + SSE 帧发射"]
ORCH --> A1 & A2 & A3 & A4 & A5
end
subgraph L3["服务层 · app/services/"]
S1[QueryService<br/>意图→SQL→解读] --- S2[RagService<br/>分块/检索/问答] --- S3[DataService<br/>GIS 取证出口]
end
subgraph L4["数据层"]
REPO["app/repositories/<br/>fire / report 仓储"] --- ORM["app/models/ · 13 张表<br/>SQLAlchemy ORM"]
PG[("PostgreSQL 16<br/>+ PostGIS 3.4<br/>+ pgvector")]
ORM --> PG
end
subgraph L5["横切层 · app/core/"]
C1[config] --- C2[security/session] --- C3[ratelimit/redact]
C4["llm.py + llm_invoker.py<br/>5 供应商×6 能力<br/>重试+熔断+降级链"] --- C5[checkpointer<br/>PostgresSaver] --- C6[observability<br/>Langfuse] --- C7[mcp_client] --- C8[reranker/memory_store/uploads]
end
API --> L1
R5 --> WF --> ORCH
R3 --> S1
R4 --> S2
R1 & R8 --> C2 & C3
A1 & A2 --> S3 --> REPO
A3 --> S2
A1 & A2 & A3 & A4 & A5 -.->|"唯一出口"| C4
ORCH --> C5
分层铁律(违反即破坏可靠性设计):
- 路由层不写 SQL、不拼提示词;服务层不感知 HTTP;Agent 不直接开 DB 会话。
- 所有 LLM 调用必须经
llm_invoker,禁止直连供应商 SDK——这是熔断、重试、降级链、token 记账生效的前提。 - 所有出向日志经
redact脱敏;所有配置回显走mask_secret。 - 并行节点只返回 delta(
steps/knowledge_results用operator.addreducer),禁止返回全量列表,防止并行写冲突。
OrchestratorAgent 用 LangGraph StateGraph 装配 八个节点。parse_task 用 LLM 结构化产出执行计划(TaskPlan),后续节点按计划执行或跳过(跳过 = no-op 节点,保住 join 屏障正确性)。
flowchart TB
START(("开始")) --> PARSE["① parse_task<br/>LLM 结构化拆解 → TaskPlan"]
PARSE --> ROUTE{"条件路由<br/>读 parsed_intent.plan"}
ROUTE -->|"plan 含 query_data"| QD["② query_data<br/>DataAgent·历史/预测检索"]
ROUTE -->|"plan 含 retrieve_knowledge"| RK["② retrieve_knowledge<br/>RagAgent·向量检索+精排"]
ROUTE -->|"两者都不含"| JOIN
QD --> JOIN["④ join 汇聚屏障"]
RK --> JOIN
JOIN --> GIS{"⑤ analyze_gis<br/>计划含 GIS 分析?"}
GIS -->|"是"| GISEX["GisAgent·空间取证<br/>PostGIS 缓冲区/统计"]
GIS -->|"否(no-op)"| GR
GISEX --> GR["⑥ generate_report<br/>ReportAgent·流式生成<br/>思考流+正文逐字推送"]
GR --> REV{"⑦ review_report<br/>低温度评审+硬护栏"}
REV -->|"✅ 0 问题:通过"| GATE
REV -->|"⚠️ 有问题且轮次<2<br/>带意见退回"| GR
REV -->|"评审自身失败<br/>degraded 转人工"| GATE
GATE["⑧ approval_gate<br/>LangGraph interrupt 暂停<br/>HITL 等待人工决策"]
GATE -->|"approve 通过"| DONE(("报告定稿"))
GATE -->|"edit 直接定稿<br/>以编辑内容为准"| DONE
GATE -->|"reject 带反馈重写<br/>revisions 清零"| GR
style PARSE fill:#e8f4fd,stroke:#2196f3
style QD fill:#e8f8ee,stroke:#4caf50
style RK fill:#e8f8ee,stroke:#4caf50
style GATE fill:#fff7e6,stroke:#ff9800
style DONE fill:#e8f8ee,stroke:#4caf50
三条循环与三态语义:
| 机制 | 规则 | 失败语义 |
|---|---|---|
| 评审循环 | review_report 用低温度 LLM + ReviewVerdict 硬护栏评审;不通过带 issues/suggestion 退回 generate_report 重写,最多 2 轮(revisions 计数) |
超 2 轮 → 携带最新评审意见强制进入审批 |
| 评审三态 | 0 问题 = 通过;有问题且轮次 <2 = 退回;评审自身调用失败 = degraded,不阻塞流水线,转人工 | 评审失败不是系统失败 |
| 审批三动作 | approve 通过定稿;edit 用户编辑后的内容直接定稿;reject 带 rejection_feedback 重写,且 revisions 清零重新计数 |
AGENT_REQUIRE_APPROVAL=False 时闸口直通 |
| 反思重试 | query_data 结果为空时 LLM 反思放宽参数(年/月/州市/视图)重查,最多 2 轮 |
仍为空 → 报告如实说明数据缺口 |
并发防冲突约定:steps / knowledge_results 使用 operator.add reducer,并行波次节点(query_data ∥ retrieve_knowledge,等深并行)只返回 delta;status 键仅由 parse_task("parsed")与 generate_report/approval_gate("completed")写入;条件路由只读 parsed_intent.plan,不读 status。
从用户点「开始任务」到报告定稿的完整消息流(含 SSE 帧协议与断点续跑):
sequenceDiagram
participant U as 用户(前端)
participant API as FastAPI /api/v1/agent
participant G as LangGraph 图
participant L as llm_invoker(熔断/降级)
participant DB as PostgreSQL(业务+检查点)
U->>API: POST /tasks {query}
API->>DB: 建 agent_tasks 行(status=running) + thread_id
API->>G: astream(thread_id, config)
Note over G: PostgresSaver 逐节点落检查点
G->>L: parse_task 结构化
L-->>G: TaskPlan
par 思考流
G-->>API: step/think 帧(思考流按任务累积全部轮次)
and 并行取证
G->>L: query_data ∥ retrieve_knowledge(等深并行)
L-->>G: data_results / knowledge_results(delta)
end
G->>G: join → analyze_gis(按计划) → generate_report
G-->>API: report_delta 帧(正文逐字) + report_snapshot
G->>G: review_report 三态
alt 通过或 degraded
G->>DB: interrupt 落盘(awaiting_approval)
else 退回
G->>G: 重写 ≤2 轮
end
G-->>API: approval 帧(前端弹出审批面板)
API-->>U: SSE 推送 + : ping 心跳(15s)
U->>API: POST /tasks/{id}/resume {approve|edit|reject}
API->>G: Command(resume=decision) 从检查点续跑
G-->>API: report/error 帧
API->>DB: 终态落库 + analysis_reports 归档
Note over API,DB: 连接中断→孤儿任务清扫线程标记 abandoned<br/>重连→GET /tasks/{id}/stream 从检查点重放
SSE 帧协议(data: {"type": ..., ...},事件间以空行分隔):
| 帧类型 | 时机 | 载荷要点 |
|---|---|---|
step |
每个节点开始/结束 | step_name、status、output 摘要 |
think |
报告生成思考流增量 | delta 文本;思考流按任务累积全部轮次 |
think_reset |
重写轮开始 | 前端清空当前思考面板 |
report_delta |
报告正文增量 | delta 文本(LLM_STREAM_ENABLED=True) |
report_snapshot |
阶段性全量 | 整段正文(重连/校对用) |
approval |
抵达审批闸口 | 报告草稿 + 评审意见,前端渲染审批面板 |
report |
定稿 | 最终 markdown + 元数据 |
error |
节点失败 | 错误消息 + 阶段;正文 ≥600 字时采纳部分稿 |
: ping |
每 15s | 注释行心跳,防反代空闲断连 |
| 层 | 技术 | 版本/说明 |
|---|---|---|
| Web 框架 | FastAPI + Uvicorn | Pydantic v2 设置管理,SSE 用 StreamingResponse |
| 智能体编排 | LangGraph | StateGraph 八节点 + interrupt HITL + PostgresSaver 检查点 |
| LLM 接入 | OpenAI 兼容协议 | 5 供应商:aliyun(百炼)/ amd / ollama / longcat / coarena |
| 数据库 | PostgreSQL 16 | PostGIS 3.4(SRID 4326 空间查询)+ pgvector(RAG 向量) |
| ORM / 迁移 | SQLAlchemy + Alembic | 启动期 ensure_columns 自愈兜底 |
| 认证 | bcrypt + JWT (HS256) | token_version 吊销 + 15h 滑动会话 |
| 空间数据 | GeoAlchemy2 / shapely | 火点、边界、缓冲区分析 |
| 观测 | Langfuse(私有化,可选) | LANGFUSE_ENABLED=False 时降级纯日志 |
| 工具化数据源 | MCP(高德天气只读 server,可选) | 失败自动降级跳过 |
| 文档识别 | 本地 MinerU2.5-Pro → 云端增强 → RapidOCR | OCR 三级兜底 |
fire_agent_back/
├── app/
│ ├── main.py # FastAPI 入口:lifespan 四步启动 + 中间件栈 + 8 组路由注册
│ ├── core/ # 横切层
│ │ ├── config.py # Pydantic Settings 全部配置项(.env 覆盖)
│ │ ├── database.py # engine/SessionLocal/get_db
│ │ ├── security.py # bcrypt 哈希 / JWT 签发校验 / token_version / get_current_user
│ │ ├── session.py # 15h 滑动会话中间件(X-Token-Refresh 重签)+ 生产启动自检
│ │ ├── ratelimit.py # 登录节流:IP+用户名 5min/5 次锁 15min,同 IP 每窗口 20 账号
│ │ ├── llm.py # 供应商注册表 + 能力矩阵 + 熔断器
│ │ ├── llm_invoker.py # 统一调用层:超时/重试/熔断/降级链/记账/流式
│ │ ├── checkpointer.py # PostgresSaver 检查点(HITL 断点续跑)
│ │ ├── redact.py # 日志脱敏 + mask_secret
│ │ ├── uploads.py # 上传白名单校验(扩展名+魔数+大小)
│ │ ├── reranker.py # DashScope text-rerank,失败降级 RRF
│ │ ├── memory_store.py # 用户偏好长期记忆(PostgresStore)
│ │ ├── observability.py # Langfuse 私有化观测
│ │ ├── mcp_client.py # MCP 工具化数据源(高德天气)
│ │ ├── report_channels.py # 报告推送通道
│ │ ├── amd_directory.py / bailian_directory.py / bailian_quota_data.py # 模型目录与配额
│ ├── agents/ # 编排层:orchestrator_agent + data/gis/rag/report 五 Agent
│ ├── workflows/ # agent_workflow:图装配 + SSE 帧发射 + 孤儿清扫
│ ├── services/ # query_service / rag_service / data_service
│ ├── repositories/ # fire_repository / report_repository
│ ├── models/ # 13 张表 ORM
│ ├── schemas/ # Pydantic 请求/响应模型
│ ├── api/v1/routes/ # 8 组路由:auth/dashboard/query/rag/agent/report/admin/media
│ └── utils/ # risk_level(后端五级判定)/ geojson
├── scripts/ # 数据导入与运维脚本(见「测试与脚本」)
├── tests/ # pytest 8 项回归
├── docs/ # 毕业论文主册/后端分册
├── alembic/ # 数据库迁移
├── docker-compose.yml # db + backend + frontend(可选 --profile observability 挂 Langfuse)
├── Dockerfile
├── init_db.py # 兼容入口 → scripts/init_db.py
└── requirements.txt
# 1. 准备环境变量(切勿提交 .env)
cp .env.example .env # 或手写;生产必须配 JWT_SECRET(≥32字节随机) 与 ADMIN_INIT_PASSWORD
# 2. 一键起三服务:fire-agent-db(仅127.0.0.1:5432) / backend(127.0.0.1:8000) / frontend(8080:80)
docker compose up -d
# 3. 导入数据(首次)
python scripts/run_all_imports.py# 1. Python 3.11+ 虚拟环境
python -m venv .venv && .venv\Scripts\activate # Windows
pip install -r requirements.txt
# 2. PostgreSQL 16 + PostGIS + pgvector 就绪后建库
python scripts/init_db.py
# 3. 启动
uvicorn app.main:app --reload --port 8000启动序列(app/main.py 的 lifespan)依次执行四步,全部幂等可重入:
flowchart LR
A["① create_all<br/>建表(幂等)"] --> B["② ensure_columns<br/>旧库缺列自愈<br/>ALTER TABLE IF NOT EXISTS"]
B --> C["③ 种子管理员<br/>口令唯一来源 ADMIN_INIT_PASSWORD<br/>生产未配→拒绝启动<br/>开发未配→回退123456+警告"]
C --> D["④ 任务自愈<br/>running→failed(中断)<br/>awaiting_approval 不动(HITL可续)<br/>清理僵尸 running 步骤行"]
D --> E["服务就绪 :8000"]
生产环境(ENV=production)另有三道关卡:模块导入期 validate_security_config() 校验 JWT_SECRET ≥32 字节且非模板占位值;ADMIN_INIT_PASSWORD 必填;/docs、/redoc、/openapi.json 全部关闭。
完整定义见 app/core/config.py。本表只列变量名与非密默认值,任何密钥不入库不入文档;
.env文件永不提交。
| 变量 | 默认值 | 用途 |
|---|---|---|
ENV |
development |
production 触发启动自检、关 API 文档 |
JWT_SECRET |
""(空) |
JWT 签名密钥;生产必填 ≥32 字节强随机 |
JWT_ALGORITHM |
HS256 |
签名算法 |
ACCESS_TOKEN_EXPIRE_MINUTES |
900 |
会话空闲上限 15h(滑动续期) |
ADMIN_INIT_PASSWORD |
"" |
种子管理员口令来源;生产必填 |
CORS_ORIGINS |
localhost:5173/4173 | 跨域白名单 |
DATABASE_URL |
postgresql://…localhost:5432/fire_agent |
业务库连接串 |
AMAP_KEY |
"" |
高德天气 MCP 数据源 |
ACTIVE_LLM_PROVIDER |
aliyun |
活跃 LLM 供应商(aliyun/amd/ollama/longcat/coarena) |
LLM_API_BASE / LLM_API_KEY |
"" |
百炼兼容端点/密钥(Key 不落文档) |
LLM_MODEL |
qwen-plus |
决策/生成主力模型 |
EMBEDDING_MODEL |
qwen3.7-text-embedding-flash |
向量模型(固定百炼) |
VISION_PROVIDER / VISION_MODEL |
aliyun / qwen-vl-plus |
视觉识别 |
ASR_MODEL / TTS_PROVIDER / TTS_MODEL |
qwen3-asr-flash / aliyun / qwen3-tts-flash |
语音 |
OCR_PROVIDER / OCR_MODEL |
local / MinerU2.5-Pro |
文档识别(local→云端→RapidOCR 三级兜底) |
AMD_API_BASE / AMD_MODEL |
https://developer.amd.com.cn/radeon/v1 / DeepSeek-V4-Flash |
AMD 供应商 |
OLLAMA_API_BASE / OLLAMA_MODEL |
http://localhost:11434/v1 / qwen2.5:7b |
本地 Ollama |
LONGCAT_API_BASE / LONGCAT_MODEL |
https://api.longcat.chat/openai / LongCat-2.5-Preview |
LongCat 供应商 |
COARENA_API_BASE / COARENA_MODEL |
https://coarena.ai/api/v1 / gemini-3-8-flash |
coarena 供应商 |
QWEN3_8_FLASH_START / QWEN3_8_FLASH_END |
""(不限) |
特定模型可用时间窗 |
KB_UPLOAD_DIR |
data/knowledge_base |
知识库文件落盘目录 |
KB_CHUNK_SIZE / KB_CHUNK_OVERLAP / KB_TOP_K |
500 / 50 / 5 |
分块大小/重叠/召回数 |
RERANK_ENABLED / RERANK_MODEL |
True / qwen3.7-text-rerank |
精排开关与模型(失败降级 RRF) |
AGENT_REQUIRE_APPROVAL |
True |
报告定稿前强制人工审批(HITL) |
LLM_STREAM_ENABLED |
True |
全链路流式;关闭回退整段返回 |
PREFERENCES_ENABLED |
True |
用户偏好长期记忆注入 |
LANGFUSE_ENABLED / LANGFUSE_HOST |
False / http://localhost:3000 |
私有化观测(Key 走环境变量不落文档) |
MCP_ENABLED |
True |
MCP 工具化数据源(失败自动降级跳过) |
GAUNTLET_CHAOS 等四项 |
关闭/空 | 红队评测注入项,运行时默认零影响(评测进程环境变量开启) |
统一信封 {code, message, data};除注册/登录外全部要求 Authorization: Bearer <JWT>;用户数据(历史/报告/知识库/任务)严格按 user_id 隔离,管理员可见全部。
认证 /api/v1/auth(auth.py)
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /register |
注册(用户名唯一校验,bcrypt 哈希) |
| POST | /login |
登录,受 ratelimit 节流:IP+用户名 5min 内 5 次失败锁 15min;同 IP 每窗口最多试 20 个账号(防撞库) |
| POST | /logout |
登出:token_version += 1 全端吊销 |
| GET / PUT | /me |
读取 / 修改个人资料 |
| PUT | /me/password |
改密(旧口令校验 + 改后吊销全部旧会话) |
智能查询 /api/v1/query(query.py)
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /parse |
LLM 意图解析 → 结构化参数(history/predict/summary + 年/月/州市/视图) |
| POST | /execute |
解析 + SQL 执行 + 文字解读,成功后落历史(同用户同文本去重,存完整结果供回显) |
| GET | /history、/history/{id} |
历史列表/详情(按用户隔离) |
| DELETE | /history、/history/{id} |
批量清空 / 单条删除 |
大屏数据 /api/v1/dashboard(dashboard.py)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /history-fires |
历史火点 GeoJSON(年份/月份/州市/等级筛选) |
| GET | /predict-risks |
预测火险 GeoJSON(GTWR 2025–2026) |
| GET | /summary |
大屏汇总统计(计数/分布/五级占比) |
知识库 /api/v1/rag(rag.py)
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /ask、/ask/stream |
RAG 问答(整段 / SSE 流式) |
| POST | /documents |
上传文档(txt/md/docx/pdf 白名单校验)→ 解析 → 分块 → 向量化入库 |
| GET | /documents、/documents/{id}/content、/documents/{id}/file |
列表 / 正文预览 / 原文件下载 |
| DELETE | /documents/{id} |
删除文档及全部 chunk |
| GET/DELETE | /history、/history/{id} |
问答历史管理 |
Agent 协作 /api/v1/agent(agent.py)
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /tasks |
发起任务(建 task 行 + thread_id,后台跑图) |
| GET | /tasks/{id}/stream |
SSE 订阅(帧协议见上;重连从检查点重放) |
| POST | /tasks/{id}/resume |
HITL 审批决策:approve / edit / reject(带反馈) |
| GET | /tasks、/tasks/{id} |
任务列表 / 详情(含 steps trace) |
| POST | /tasks/{id}/cancel、/tasks/{id}/retry |
取消 / 重试 |
| DELETE | /tasks/{id} |
删除任务 |
| GET | /capabilities |
供应商能力矩阵与可用性 |
| GET | /status |
编排器运行状态 |
报告中心 /api/v1/reports(report.py)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /list、/{id} |
列表 / 详情 |
| POST | /generate |
独立生成报告(不走 Agent 全流程) |
| GET | /export/{id} |
导出 md / html |
| DELETE | /{id} |
删除 |
视觉与语音 /api/v1/vision(media.py)
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /analyze |
上传图片 → 视觉模型识别火情 → 落 vision_history |
| GET/DELETE | /history、/history/{id}、/image/{id} |
识别历史管理 / 原图回看 |
| POST | /audio/transcriptions |
ASR 语音转文本(qwen3-asr-flash) |
| POST | /audio/speech |
TTS 文本转语音(qwen3-tts-flash) |
系统管理 /api/v1/admin(admin.py,文件级 fail-closed:非 admin 角色整文件 403)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET / POST | /config |
运行时配置读取 / 热更新(密钥字段 mask_secret 脱敏回显) |
| POST | /test/db、/test/llm |
数据库 / LLM 连通性测试 |
| GET | /llm/models、/model-status、/capabilities 相关 |
模型目录 / 各供应商健康与熔断状态 |
| GET | /bailian/quota |
百炼模型目录与配额 |
| GET | /status、/logs |
系统体检 / 运行日志 |
| GET | /users、PUT /users/{id}/role、DELETE /users/{id} |
用户管理(删除用户连带清理其数据) |
另有两个无鉴权存活探针:GET /、GET /health,仅返回 {"status":"ok"},不回显项目指纹。
统一调用层 app/core/llm_invoker.py 是全系统唯一 LLM 出口:能力矩阵路由 → 超时/重试 → 熔断(含半开)→ 供应商降级链 → token 记账。Embedding 固定走百炼(向量一致性),其余能力均可切换供应商。
stateDiagram-v2
[*] --> Closed
Closed --> Open: 连续失败≥阈值<br/>(记录 opened_at)
Open --> HalfOpen: 冷却时间到<br/>放行探测请求
HalfOpen --> Closed: 探测成功<br/>计数归零
HalfOpen --> Open: 探测失败<br/>重置冷却
Open --> Open: 直接快速失败<br/>触发降级链
flowchart LR
REQ["invoke_llm / invoke_structured / stream_llm"] --> ROUTE{"能力路由<br/>chat/vision/embedding/<br/>rerank/asr/tts"}
ROUTE --> TRY["主供应商<br/>超时+指数退避重试"]
TRY -->|"成功"| OK["返回 + token 记账"]
TRY -->|"熔断 Open"| FB1["降级链下一供应商"]
FB1 --> TRY2["次选供应商尝试"]
TRY2 -->|"全部失败"| DEG["结构化降级返回<br/>/ degraded 标记<br/>上层三态兜底"]
TRY2 -->|"成功"| OK
默认模型映射:决策 qwen-plus、视觉 qwen-vl-plus、向量 qwen3.7-text-embedding-flash、精排 qwen3.7-text-rerank、ASR qwen3-asr-flash、TTS qwen3-tts-flash、OCR 本地 MinerU2.5-Pro、AMD DeepSeek-V4-Flash、Ollama qwen2.5:7b、LongCat LongCat-2.5-Preview、coarena gemini-3-8-flash。
flowchart TB
UP["上传 txt/md/docx/pdf<br/>uploads 白名单校验"] --> OCR["解析三级兜底<br/>本地 MinerU2.5-Pro → 云端增强(amd) → RapidOCR"]
OCR --> CHUNK["分块 500 字 / 重叠 50<br(KB_CHUNK_SIZE/OVERLAP)"]
CHUNK --> EMB["百炼向量化<br/>qwen3.7-text-embedding-flash"]
EMB --> PGVEC[("pgvector<br/>kb_chunks")]
Q["用户提问"] --> RETR["pgvector 相似检索<br/>top_k=5"]
RETR --> RERANK{"RERANK_ENABLED?"}
RERANK -->|"是"| RR["qwen3.7-text-rerank 精排"]
RERANK -->|"或精排失败"| RRF["RRF 融合保原序"]
RR & RRF --> GEN["流式生成回答<br/>引用来源标注"]
GEN --> HIS["rag_history 落库"]
- 火情识别:
POST /api/v1/vision/analyze收图 →VISION_PROVIDER路由(aliyunqwen-vl-plus/ amd)→ 结构化识别结论落vision_history,GET /image/{id}鉴权回看原图。 - ASR/TTS:同一路由文件,模型与供应商均可经 admin 配置热切换;调用同样走
llm_invoker计入记账。
13 张业务表(PostgreSQL 16,空间列 SRID 4326):
erDiagram
users ||--o{ query_history : "user_id"
users ||--o{ rag_history : "user_id"
users ||--o{ analysis_reports : "user_id"
users ||--o{ agent_tasks : "user_id"
users ||--o{ kb_documents : "user_id"
users ||--o{ vision_history : "user_id"
agent_tasks ||--o{ agent_task_steps : "task_id"
kb_documents ||--o{ kb_chunks : "doc_id"
region_boundaries ||--o{ historical_fire_points : "空间关联(州市)"
users { int id PK "username·password_hash·role·token_version·is_active·last_seen_at" }
historical_fire_points { bigint id "5411条·经纬度·年月·州市·火险等级(PostGIS)" }
predicted_fire_risks { int id "GTWR预测 2025-2026·风险值" }
region_boundaries { int id "16州市边界(多边形)" }
emergency_resources { int id "应急资源点位" }
kb_documents { int id "知识库文档·user_id" }
kb_chunks { int id "分块+向量(pgvector)" }
query_history { int id "查询文本+完整结果JSON" }
rag_history { int id "问答对+引用" }
analysis_reports { int id "报告md·llm_provider/model/tokens/degraded" }
agent_tasks { int id "状态机·thread_id·final_summary" }
agent_task_steps { int id "节点trace·思考流·产物" }
vision_history { int id "识别结论+原图路径" }
迁移策略:Alembic 管理正式迁移;lifespan 第二步 ensure_columns 对旧库幂等补列(如 users.token_version、analysis_reports.llm_tokens),保证「拉代码即起服务」。
| 防线 | 实现 |
|---|---|
| 口令存储 | bcrypt(app/core/security.py),永不落明文日志 |
| 会话 | JWT HS256 + token_version 吊销(登出/改密全端失效) |
| 滑动续期 | SlidingSessionMiddleware:15h 空闲判定,每次带凭证请求重签新 token 放 X-Token-Refresh 头,CORS expose_headers 放行前端读取 |
| 登录节流 | app/core/ratelimit.py:进程内存实现,IP+用户名 5min/5 次失败锁 15min;同 IP 每窗口 20 账号防撞库 |
| 管理端 | admin.py 文件级 fail-closed:依赖注入在文件头统一校验 role |
| 上传安全 | app/core/uploads.py:扩展名白名单 + 文件魔数校验 + 大小上限 |
| 日志脱敏 | app/core/redact.py 全量出向日志过滤 + mask_secret 配置回显 |
| 生产加固 | 启动自检(JWT_SECRET 强度/模板值黑名单、ADMIN_INIT_PASSWORD 必填)、关闭三文档路由、安全响应头中间件(nosniff/DENY/no-referrer/permissions-policy,摘 Server/X-Powered-By) |
- 步骤 trace 全量入库:每个节点执行写入
agent_task_steps(含思考流,单步落库上限 12000 字,思考每累积 400 字即时落库一次),任务详情页可完整回放。 - SSE 实时流:见「一次任务的完整时序」;孤儿任务清扫线程处理连接中断后的僵尸任务。
- Langfuse(可选):
docker compose --profile observability up -d拉起私有化 Langfuse(:3000),LANGFUSE_ENABLED=True+ 密钥后记录 LLM 调用链;未启用降级纯日志。 - 复读防护:
_StreamLoopGuard句子级逐字计数(思考 4 次/正文 6 次阈值)+ 字符 bigram Jaccard ≥0.72 近似簇检测 + 后缀块重复 + 多窗口确认,命中即在重复起点截断。
pytest 回归 8 项(tests/):test_sliding_session(滑动续期)、test_review_tri_state(评审三态)、test_stream_loop_guard(复读防护)、test_report_replay(报告重放)、test_log_redaction(日志脱敏)、test_upload_validation(上传校验)、test_admin_delete_user(管理员删户连带清理)、test_dashboard_summary_fields(大屏字段契约)。
pytest -v # 全量回归
python scripts/init_db.py # 建库建表
python scripts/migrate_pgvector.py # pgvector 迁移
python scripts/run_all_imports.py # 一键导入:火点+预测+边界
python scripts/import_fire_points.py # 单独导入历史火点
python scripts/import_predict_risks.py # 单独导入 GTWR 预测
python scripts/import_region_boundaries.py # 单独导入州市边界
python scripts/check_auth_coverage.py # 端点鉴权覆盖检查(防裸奔端点)
python scripts/eval_regression.py # 质量回归评测(golden_set.json 驱动)flowchart LR
subgraph HOST["单机 Docker Compose"]
direction TB
NG["frontend 容器<br/>Nginx :8080→80<br/>静态资源 + 反代"]
BE["backend 容器<br/>uvicorn :8000"]
DB[("fire-agent-db 容器<br/>PostgreSQL16+PostGIS+pgvector<br/>端口仅绑 127.0.0.1:5432")]
LF["Langfuse 容器(可选 profile)<br/>:3000"]
end
USER(("用户")) -->|:8080| NG
NG -->|"/api 反代·SSE 关缓冲 1800s"| BE
BE --> DB
BE -.->|LANGFUSE_ENABLED| LF
Nginx 关键配置:/api 反代关闭缓冲(proxy_buffering off)并放宽读超时至 1800s 以承载 SSE 长连接;/tianditu 天地图瓦片反代去掉 Referer;SPA history 路由回退 index.html。三服务端口均只绑定 127.0.0.1,由 Nginx 统一对外。
| 文档 | 内容 |
|---|---|
| 后端.md | 深度设计:逐模块逐端点实现讲解、LLM 可靠性、评审/审批语义、SSE 协议 |
| 整体实现.md | 全链路实现拆解:从一次请求到一次任务落库的每一步 |
| AGENT_UPGRADE_PLAN.md | P1/P2 演进方案与落地清单 |
| docs/毕业论文主册.md · docs/毕业论文后端分册.md | 论文文本 |
前端仓库 fire_agent_front |
Vue 3 + OpenLayers 可视化端,README 含功能演示动图 |