Skip to content

About

在我毕业设计纯前端大屏(地址: https://gitee.com/wjl2004/Fire_hazard_Yunnan_system )展示的基础上改成agent风格系统.焰哨 FlameSentry · 多智能体森林火险预警平台:LangGraph 8 节点编排(并行 fan-out + 评审循环)+ SSE 节点级实时推送 + HITL 人工审批 + RAG 知识库,Vue3 八大模块(2D/3D 数字孪生、双主题、语音交互)× FastAPI,把「看数据」升级为「系统替你研判数据」。Multi-agent wildfire risk platform.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

焰哨 · 森林火险多智能体分析与预警平台(后端)

版本 1.0.1 · 更新时间 2026-11-17 · 本文档由当前仓库代码逐文件核对撰写;深度设计文档见 后端.md,全链路实现拆解见 整体实现.md

焰哨后端是基于 FastAPI + LangGraph 构建的森林火险智能分析与预警服务。它以云南 16 州市、5411 条历史火点 与 GTWR 预测火险数据为底座,通过 六个协作智能体(编排、数据、GIS、RAG、报告、评审)组成的多智能体流水线,把一次自然语言指令变成「意图解析 → 并行取证 → 知识增强 → GIS 叠加 → 报告生成 → 自动评审 → 人工审批」的完整闭环,全程 SSE 流式推送,支持 HITL 人工审批闸口 与 Postgres 检查点断点续跑。

Python FastAPI LangGraph PostgreSQL Docker


目录


功能地图

模块 入口路由 能力(实现位置)
智能查询 /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
Loading

分层铁律(违反即破坏可靠性设计):

  1. 路由层不写 SQL、不拼提示词;服务层不感知 HTTP;Agent 不直接开 DB 会话。
  2. 所有 LLM 调用必须经 llm_invoker,禁止直连供应商 SDK——这是熔断、重试、降级链、token 记账生效的前提。
  3. 所有出向日志经 redact 脱敏;所有配置回显走 mask_secret。
  4. 并行节点只返回 delta(steps / knowledge_results 用 operator.add reducer),禁止返回全量列表,防止并行写冲突。

多智能体工作流

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
Loading

三条循环与三态语义:

机制 规则 失败语义
评审循环 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 从检查点重放
Loading

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

快速开始

方式一:Docker Compose(推荐)

# 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"]
Loading

生产环境(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 等四项 关闭/空 红队评测注入项,运行时默认零影响(评测进程环境变量开启)

API 总览(58 个端点)

统一信封 {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"},不回显项目指纹。

LLM 多供应商接入

统一调用层 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/>触发降级链
Loading
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
Loading

默认模型映射:决策 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。

RAG 知识库检索

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 落库"]
Loading

视觉与语音

  • 火情识别:POST /api/v1/vision/analyze 收图 → VISION_PROVIDER 路由(aliyun qwen-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 "识别结论+原图路径" }
Loading

迁移策略: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
Loading

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 含功能演示动图

About

在我毕业设计纯前端大屏(地址: https://gitee.com/wjl2004/Fire_hazard_Yunnan_system )展示的基础上改成agent风格系统.焰哨 FlameSentry · 多智能体森林火险预警平台:LangGraph 8 节点编排(并行 fan-out + 评审循环)+ SSE 节点级实时推送 + HITL 人工审批 + RAG 知识库,Vue3 八大模块(2D/3D 数字孪生、双主题、语音交互)× FastAPI,把「看数据」升级为「系统替你研判数据」。Multi-agent wildfire risk platform.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages