AI 事故信息采集 API（LangGraph 迁移分支）

本分支把事故采集、拍照和信息核实从 FastGPT workflow 迁移到嵌入式 LangGraph。 文本四接口通过 AGENT_BACKEND 选择 FastGPT 或 LangGraph，HTTP schema 与 SSE 事件保持兼容。 迁移作业计划见 docs/langgraph-backend-migration-plan.md， 字段兼容约定见 docs/assignment6-compat.md。

环境与安装

Python 3.11 使用 Conda 环境 py3.11（见 AGENTS.md）。

conda activate py3.11
pip install -r requirements.txt

# 项目仍使用该 SDK 支持 FastGPT 路径；源码在独立仓库维护。
pip install -e /path/to/fastgpt-python-sdk

配置与后端选择

复制 .env.example 为 .env 并填写配置；.env 不进入 Git。

• FastGPT：AGENT_BACKEND=fastgpt，填写 ANALYSIS_SERVICE_URL、ANALYSIS_AUTH_TOKEN、APP_ID。
• LangGraph：AGENT_BACKEND=langgraph，按 .env.example 填写命名 LLM 配置， 由 LLM_PROVIDER 选择模型；文本后端不要求 FastGPT 凭证。
• LangGraph 存储：AGENT_STORAGE=memory|sqlite|postgresql。每个实例只选一个，修改后重启。 DATABASE_URL 不控制 LangGraph 会话存储，切换数据库不自动搬迁旧数据。

本地 SQLite 示例：

AGENT_BACKEND=langgraph
AGENT_STORAGE=sqlite
AGENT_SQLITE_PATH=./data/agent.sqlite3
AGENT_DB_AUTO_MIGRATE=false

首次初始化和运行：

conda run -n py3.11 python -m src.storage.migrate --backend sqlite
conda run -n py3.11 python -m src.serve --port 8000

PostgreSQL 的连接池、迁移、本地 compose 与多 worker 部署见 docs/agent-storage.md。Windows 使用 python -m src.serve， 它为 psycopg 选择兼容的事件循环；Linux 也可用常规 uvicorn 命令启动。

HTTP 接口

• GET /：存活检查。
• POST /chat：对话；?stream=true 使用真实增量 SSE。
• POST /set_info、POST /get_info：业务字段读写，不调用模型。
• DELETE /delete_session：清理 checkpoint 和业务状态，真实存储错误返回失败。
• SQLite/PostgreSQL 模式可给 /chat 添加 Idempotency-Key 请求头， 重放已提交结果；复用 key 但请求内容不同返回业务码 409。

SSE 的 error 是失败终止，done 是成功结束。正文可以先流出， 调用方必须在收到 done 后才将本轮视为成功。needFormUpdate=false 只隐藏对外差量，不影响内部字段提交。

测试

conda run -n py3.11 python -m pytest -q

测试覆盖公共 schema、两后端适配、流式校验/取消、会话串行、字段别名、错误码与持久化恢复。 SQLite 集成测试使用临时真实文件；PostgreSQL 集成测试需要 AGENT_TEST_POSTGRES_DSN 指向隔离测试库。未配置时 PostgreSQL 用例会明确跳过。 两端都有直接退出子进程的恢复测试，不调用真实 LLM。

真实模型评测使用 evals/run.py，结果按每轮模型与代码版本单独保存， 历史轮次通过率不代替当前提交的业务验收。

目录结构

src/
  api/endpoints.py        # HTTP schema、阶段标签解析、SSE 协议
  agent/                  # 流程图、节点、版本化提示词与模型服务
  backends/               # FastGPT / LangGraph 中立适配
  services/               # 四接口应用服务、字段注册表、会话锁
  storage/                # SQLite / PostgreSQL、轮次日志、migration
  core/fastgpt_client.py   # 后端与存储生命周期、依赖注入
  serve.py                # 跨平台单 worker 启动入口
  schemas/models.py       # 公共请求/响应模型
test/storage/             # 两种数据库的真实集成与故障恢复测试
evals/                    # 真实模型评测用例与 runner

部署边界

• memory 是临时存储，重启丢失；SQLite 限定单实例、单 worker。
• PostgreSQL 使用数据库级会话锁、版本和 epoch 校验；仍需按目标负载验证池容量与吞吐。
• 业务快照是已提交状态的权威源，旧 checkpoint 执行进度在下一轮重建， 不承诺从未提交的 LLM 调用中途续跑。
• 语音 WebSocket 管线仍有独立配置，不由本次数据库选择自动迁移。
• 未知字段写入、敏感字段访问边界等兼容事项继续按兼容清单处理。