- Add complete Python backend (Litestar + LangGraph) with chat, conversations, tickets APIs - Add GitHub Actions workflow for auto-deploying backend to Azure Web App (soc-backend) - Add gunicorn to requirements.txt for production serving - Update CLAUDE.md and EXTERNAL_SERVICES.md with latest config - Remove obsolete claudehd.md (merged into gpthd.md) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
25 KiB
25 KiB
SOC 项目后端功能方案(基于 LangChain,按功能拆解)
约束:在未获得明确允许前,不修改前端交互,只补后端能力、编排链路和数据层。 目标:严格围绕当前
~/go/soc这个 Gemini 风格前端,按“每个功能用什么技术完成什么功能”来写,核心框架改为 LangChain / LangGraph,不再以 FastAPI 作为方案重点。
1. 对话流式回复
要完成什么功能
- 用户在当前聊天输入框发送消息
- 后端实时返回回答内容
- 支持“思考中 / 检索中 / 生成中”的状态
- 不改变现有前端交互,只替换当前前端
simulateAIResponse()
用什么技术
- LangChain:负责组织提示词、消息上下文、模型调用
- LangGraph:负责整个对话节点编排与状态流转
- Azure OpenAI:生成最终回答
- SSE:把 LangChain/LangGraph 执行过程和回答流式推给前端
- PostgreSQL:保存会话和消息记录
怎么落地
- 以
LangGraph StateGraph建立一个对话图:receive_messageload_historyroute_toolscall_llmpersist_message
- 前端发送消息后,后端触发 graph 执行
- Azure OpenAI 通过 LangChain chat model 调用
- 生成的 token 和中间状态通过 SSE 返回给前端
输出结果
- 前端仍然保持当前 Gemini 风格聊天交互
- 从 mock 回复升级为真实流式 AI 回复
- 后续所有工具调用都能接到同一个 graph 里
2. 会话管理
要完成什么功能
- 左侧历史会话列表从真实数据读取
- 支持新建、切换、删除会话
- 支持自动生成标题
- 会话上下文可在 LangChain 中继续使用
用什么技术
- PostgreSQL:保存 conversation 和 message
- LangChain Memory / Message History 抽象:管理历史消息上下文
- SQLAlchemy / SQLModel:管理数据表
怎么落地
- conversations/messages 数据存入 PostgreSQL
- 在 LangChain 层使用
BaseChatMessageHistory风格封装数据库消息 - 每次进入 graph 时先加载历史消息
- 标题生成可以由 LLM 在首轮消息后自动归纳
输出结果
- 当前左侧 mock 会话可以替换为真实会话记录
- 后端真正具备多轮上下文记忆能力
3. 内部知识库检索
要完成什么功能
- 当用户问产品、方案、配置、内部文档时
- 自动检索内部知识库
- 再让模型基于检索结果生成回答
- 回答中附带引用来源
用什么技术
- LangChain Tool:把 KB_AGENT 封装成知识库工具
- KB_AGENT 接口:作为实际搜索源
- Azure OpenAI:总结检索结果并生成回答
- LangGraph:决定何时调用知识库节点
怎么落地
- 编写
kb_search_tool - 工具内部调用
KB_AGENT_URL + KB_AGENT_SEARCH_PATH - 返回统一的文档列表结构
- graph 中当识别为内部知识类问题时,先进入
kb_search节点,再进入llm_answer
输出结果
- 产品知识问答不再靠模型空想
- 回答可基于真实内部资料
- 更适合售前、售后、研发支持
4. 外部 AI 搜索
要完成什么功能
- 处理实时互联网问题、行业动态、外部资料调研
- 支持搜索、网页读取、重排
- 支持 fast / deep / auto 三种搜索质量
- 后续支持图片和视频检索结果
用什么技术
- LangChain Tool:封装外部搜索工具链
- Jina Search API:外部搜索
- Jina Reader:网页正文读取
- Rerank 模型:重排结果
- LangGraph:编排 Search -> Read -> Rerank -> Answer
- Azure OpenAI:生成最终总结回答
怎么落地
- 分成三个 tool:
web_search_toolweb_read_toolrerank_tool
- 在 graph 中建立外部搜索链路:
- 搜索候选
- 读取正文
- 重排结果
- 将高质量上下文交给 LLM
fast/deep/auto可作为 graph state 中的参数
输出结果
- 外部信息回答准确度显著提升
- 满足文档要求里的企业级外部搜索能力
- 为后续图片、视频结果展示预留结构
5. 工单系统只读接入
要完成什么功能
- 查询工单列表
- 查询工单详情
- 汇总 P0/P1 工单
- 支持聊天中分析工单趋势、共性问题、故障重点
- 替换当前前端 mock 工单摘要
用什么技术
- LangChain Tool:把 gongdan API 封装为工单工具
- Gongdan HTTP API:工单实际数据源
- Azure OpenAI:对工单结果做总结和归纳
- PostgreSQL(可选缓存):保存查询结果和摘要缓存
怎么落地
- 编写工具:
ticket_list_toolticket_detail_toolticket_summary_tool
- 当用户问题涉及工单时,graph 路由到 ticket 节点
- 工具取回结果后,再由 LLM 进行总结
- 当前前端的 TicketSummary 数据以后改成读取真实接口结果,但不改交互样式
输出结果
- 工单分析能力可直接在聊天里使用
- 首页/聊天区的工单摘要可从 mock 变成真实数据
6. 文档生成
要完成什么功能
- 用户要求生成方案、汇报、纪要、总结文档时
- 后端自动进入文档生成流程
- 返回任务状态和结果
- 生成正式文档链接或结果卡片
用什么技术
- LangChain Tool / Runnable:封装文档生成能力
- Doc Creator Agent HTTP API:实际生成正式文档
- LangGraph:把“文档生成”作为 graph 的分支节点
- PostgreSQL:保存文档任务记录
- Azure OpenAI:先整理文档结构或提纲
怎么落地
- graph 中识别“生成文档”类意图
- 先用 LLM 生成结构化文档提纲
- 再调用 doc creator agent
- 把任务状态写入数据库
- 前端依旧保持聊天式入口,只在消息中显示结果卡片
输出结果
- 销售、售前、汇报场景可以直接从聊天进入正式文档输出
- 文档生成成为对话系统中的标准能力节点
7. 沙盒代码执行
要完成什么功能
- 分析 CSV、JSON、日志、结构化数据
- 在安全环境中执行代码
- 返回分析结果、图表和文件
- 不改变前端交互,只把结果塞回当前聊天流里
用什么技术
- LangChain Tool:把沙盒能力封装为可调用工具
- Daytona Sandbox:安全执行环境
- Python 数据工具链:pandas、matplotlib、json、csv
- LangGraph:按意图路由到 sandbox 节点
- PostgreSQL:保存执行记录
怎么落地
- 第一阶段不开放任意代码执行
- 只先封装几个固定工具:
csv_summary_tooljson_transform_tooldata_analysis_toolchart_generate_tool
- graph 根据问题和附件类型决定是否调用 sandbox
输出结果
- 后端不仅能“回答”,还能“执行”和“计算”
- 数据类问题能返回真正算出来的结果
8. 附件上传与解析
要完成什么功能
- 接收用户上传的附件
- 保存附件元数据
- 提取文本内容进入上下文
- 为知识问答、文档生成、沙盒分析提供输入
用什么技术
- 对象存储/本地存储:保存附件
- LangChain Document Loader:解析 PDF、DOCX、TXT、CSV 等文件
- PostgreSQL:保存附件元数据
- LangGraph:把附件解析结果接入 graph state
怎么落地
- 上传后先保存附件和元数据
- 再用 LangChain loader 抽取文本
- 将解析结果挂到当前会话 state 中
- 当用户继续提问时,graph 可以把附件内容作为上下文输入 LLM 或工具
输出结果
- 未来可以真正支持“基于附件提问”和“基于附件分析”
- 为文档生成和沙盒执行提供输入材料
9. 工具编排层
要完成什么功能
- 判断用户当前问题到底需要哪种能力
- 决定先查 KB、先查工单、还是先查外部搜索
- 决定是否触发文档生成或沙盒分析
- 把多个工具结果统一整理给模型
用什么技术
- LangGraph:整个系统的核心编排框架
- LangChain Tools:封装 KB、Search、Tickets、Docs、Sandbox
- Azure OpenAI:辅助做意图判断、结果总结
怎么落地
- graph 中至少有这些节点:
routerkb_searchweb_searchticket_querydoc_generatesandbox_runllm_answerpersist
- 第一阶段可以先“规则路由 + LLM总结”
- 第二阶段再升级为“LLM路由 + 工具调用决策”
输出结果
- 后端不再是散乱接口集合,而是统一 Agent 编排系统
- 前端只保留一个 Gemini 风格聊天入口即可
10. 数据持久化与基础设施
要完成什么功能
- 保存历史会话
- 保存消息记录
- 保存工具调用记录
- 保存附件记录
- 保存文档任务记录
- 保存 graph 执行状态和日志
- 提升缓存能力、异步任务能力和文件持久化能力
用什么技术
- PostgreSQL:主数据库,保存会话、消息、任务、工具记录
- LangGraph Checkpointer / State Persistence:保存 graph 执行状态
- Redis:缓存热点结果、会话临时状态、短期上下文、速率控制
- Azure Storage Account:保存附件、图表、导出文件、文档产物
- Azure Service Bus:承载异步任务与解耦长链路处理
怎么落地
- PostgreSQL 中至少建立以下表:
conversationsmessagestool_runsattachmentsdocument_tasksgraph_runs
- Redis 用于:
- 外部搜索结果缓存
- KB 搜索缓存
- 工单摘要缓存
- 正在运行的 graph/session 临时状态
- SSE 会话短状态同步
- Azure Storage Account 用于:
- 用户上传附件原始文件
- Sandbox 输出文件
- 图表与中间产物
- 文档生成结果文件
- Azure Service Bus 用于:
- 文档生成异步任务派发
- Sandbox 长任务调度
- 外部搜索深度模式异步并发编排
- 后续告警/通知类事件扩展
输出结果
- 对话、工具、任务都有追踪记录
- graph 执行链路具备可恢复能力
- 系统具备缓存、异步任务和文件持久化基础设施
11. Redis 缓存层
要完成什么功能
- 降低外部接口重复调用成本
- 提升对话链路响应速度
- 处理短期状态、热点数据和限流控制
用什么技术
- Azure Redis:缓存层
- LangChain / LangGraph 外围状态管理:结合缓存保存中间态
怎么落地
- 缓存这些内容:
- 相同 query 的 KB 搜索结果
- 相同 query 的外部搜索与重排结果
- 工单摘要结果
- 文档生成任务短状态
- 会话级短期上下文摘要
- 为外部搜索和知识库增加 TTL
- 为 Service Bus 异步任务增加状态缓存
输出结果
- 系统速度更稳定
- 外部服务成本更低
- 可支撑更高并发下的会话请求
12. 存储账户(文件与产物存储)
要完成什么功能
- 持久化用户上传附件
- 保存文档生成结果
- 保存 Sandbox 执行生成的图表/文件
- 为前端提供附件与结果文件访问地址
用什么技术
- Azure Blob Storage:统一文件对象存储
- LangChain Document Loader:结合存储文件做解析
怎么落地
- 上传文件后先保存到 Blob Storage
- 数据库中记录 blob URL、文件类型、所属消息/会话
- 文档生成与 Sandbox 产物统一落到 Blob Storage
- 前端保持现有交互,仅在消息中附带文件结果卡片或链接
输出结果
- 所有附件和中间产物有统一落盘位置
- 后续分析、下载、追踪都更方便
13. Service Bus 异步任务层
要完成什么功能
- 处理长耗时任务
- 解耦即时对话链路和后台异步处理链路
- 支持重试、失败恢复、延后处理
用什么技术
- Azure Service Bus:消息队列 / 异步任务总线
- LangGraph:消费任务后继续执行长链路节点
怎么落地
- 把这些任务异步化:
- 文档生成
- Sandbox 长任务
- 深度外部搜索
- 未来的大批量分析任务
- 聊天主链路先返回“任务已受理”状态
- Worker 从 Service Bus 拉取任务继续执行
- 执行结果写数据库和存储账户,再回推前端
输出结果
- 避免主对话链路阻塞
- 长任务处理更稳定
- 适合企业级系统扩展
14. MCP 方式接入外部搜索
要完成什么功能
- 利用
https://mcp.jina.ai/sse这一类能力,以 MCP 方式接入外部搜索 - 让外部搜索不只是普通 HTTP API,而是可作为标准工具节点接入 LangChain / LangGraph
用什么技术
- MCP(Model Context Protocol):统一工具协议
- Jina MCP SSE / v1:外部搜索与读取能力来源
- LangChain Tool 封装层:把 MCP 调用转换成 graph 可调用工具
怎么落地
- 优先测试 Jina 提供的
/sse和/v1两种入口 - 将 Search 和 Read 分别封装成两个 tool
- 在外部搜索节点中统一走 MCP 接入层,保留将来替换搜索供应商的可能
- 重排仍保留单独节点,以便保障搜索质量控制
输出结果
- 外部搜索链路更标准化
- 更容易扩展到更多 MCP 服务
- 对 LangChain / LangGraph 编排更友好
15. 基于当前前端代码补充的后端缺口与完善方案
这一章专门对应当前前端已经存在、但此前后端方案没有完整覆盖的功能点。不含认证和权限,只补业务后端能力。
15.1 消息反馈(赞 / 踩)
要完成什么
- 用户对 assistant 消息进行点赞或点踩
- 后端记录反馈结果
- 后续可用于回答质量分析、提示词优化和问题回溯
用什么技术
- PostgreSQL:保存反馈记录
- LangGraph 旁路记录:反馈不进入主对话 graph
- Redis(可选):做短期统计缓存
怎么落地
- 新增表:
message_feedbackidmessage_idconversation_idfeedback_type(up/down)reason(可空,后续扩展)created_at
- 新增接口:
POST /api/messages/{id}/feedback
- 前端点击赞/踩后直接调用该接口
- 第一阶段先只记录
up/down,不做复杂原因分类
15.2 模型切换映射
要完成什么
- 前端已有 Flash / Pro 与顶部模型选择入口
- 第一阶段后端先统一固定使用 GPT-5.4
- 但保留字段和映射结构,后续再扩展多模型、多链路
用什么技术
- LangChain model wrapper:模型封装
- LangGraph state:保存
model_profile - PostgreSQL conversation metadata:记录选择结果
怎么落地
- 前端若传模型字段,第一阶段统一映射为:
model_provider = azure_openaimodel_name = gpt-5.4
- 保留 metadata 字段:
selected_modelselected_mode
- 当前只做字段记录与透传,不做真正多模型切换
- 第二阶段再扩为 flash/pro 对应不同 graph 策略
15.3 工具显式开关控制
要完成什么
- 前端工具 chips:
- 搜索
- 内部知识库
- 沙盒
- 文档生成
- 用户手动启用哪些工具,后端就只允许调用这些工具
- 用户未选择时,后端才走自动路由
用什么技术
- LangGraph state:保存当前消息工具选择
- LangChain tools registry:统一工具注册
- tool allowlist / denylist:工具调用控制
怎么落地
- 前端发消息时附带:
{
"enabled_tools": ["search", "knowledge"]
}
- graph state 增加:
enabled_toolstool_selection_mode(auto/manual)
- router 节点规则:
manual模式:只能从 allowlist 中路由auto模式:按规则或模型自由决策
- 工具执行前统一做可用性校验
15.4 多文件上传与消息绑定
要完成什么
- 一次上传多个文件
- 每个文件单独保存
- 文件和某条消息绑定
- 文件可参与知识问答、搜索、Sandbox 分析和文档生成
用什么技术
- Azure Blob Storage:存储文件
- PostgreSQL:存储附件元数据
- LangChain Document Loaders:解析附件内容
- 消息-附件关联机制:支撑多文件场景
怎么落地
- 新增表:
attachmentsidconversation_idmessage_id(允许先空,待消息发送后再绑定)file_namecontent_typestorage_urlparse_statusparsed_textcreated_at
- 新增接口:
POST /api/attachmentsPOST /api/messages/{id}/attachments/bind
- 推荐流程:
- 前端先上传多个文件
- 后端返回 attachment ids
- 前端发消息时附带 attachment ids
- 后端完成消息与附件绑定
- 解析流程异步化,避免阻塞主聊天链路
15.5 扩展程序连接管理
要完成什么
- 支持扩展程序的连接、断开、修改 key、查看状态
- 页面刷新后仍保留扩展连接状态
- 扩展状态可被后端 graph 感知
用什么技术
- PostgreSQL:保存扩展配置与状态
- 加密存储机制:保存敏感配置
- extension registry:统一扩展管理
- LangChain tool 注册机制:根据扩展状态暴露工具
怎么落地
- 新增表:
extensionsidextension_type(ticket/sales/cloud)display_namestatusconfig_encryptedlast_check_atlast_check_status
- 新增接口:
GET /api/extensionsPOST /api/extensions/{type}/connectPOST /api/extensions/{type}/disconnectPOST /api/extensions/{type}/validate
- 第一阶段先完成工单系统全链路,销售和云管先保留扩展框架
15.6 销售系统 / 云管系统预留
要完成什么
- 虽然当前两套系统还在开发,但后端要预留统一扩展接入结构
- 避免未来工单、销售、云管三套系统接入方式不一致
用什么技术
- 统一 extension schema
- summary provider 接口
- tool provider 接口
- connection config schema
怎么落地
- 一期不要求真实接入销售/云管 API
- 但必须预留:
- 扩展类型定义
- tool 注册入口
- summary 注册入口
- 状态位和配置结构
- 后续新增业务系统时不需要推翻现有后端结构
15.7 通用扩展摘要机制
要完成什么
- 不只是工单系统,未来销售、云管系统接入后,也能输出首页/对话页摘要卡片
- 后端统一提供摘要机制
用什么技术
- summary provider registry:每个扩展实现自己的摘要提供者
- Redis:缓存摘要结果
- PostgreSQL:记录摘要生成时间与状态
- LangChain summarizer(可选):对原始数据做摘要
怎么落地
- 新增统一摘要接口:
GET /api/extensions/summaries
- 返回结构示例:
[
{
"extension_type": "ticket",
"status": "connected",
"summary_type": "ticket_summary",
"data": {}
}
]
- 第一阶段先实现 ticket summary provider
- 但接口设计按多扩展统一返回
15.8 结构化消息块协议
要完成什么
- 后端不能只返回纯文本
- 需要支持:
- 文本
- 引用来源
- 摘要卡片
- 文件结果
- 工具状态
- 错误块
用什么技术
- LangGraph 标准化事件输出
- message block schema
- 前后端统一 JSON 协议
怎么落地
- 定义统一 block 结构:
{
"type": "text | citation | summary_card | artifact | tool_status | error",
"payload": {}
}
- assistant message 最终存储结构:
{
"id": "...",
"blocks": []
}
- SSE 中间态也复用 block/event 体系
- 第一阶段前端至少支持:
texttool_statuscitationsummary_card
15.9 长任务状态回传
要完成什么
- 文档生成、Sandbox 数据分析、深度搜索等任务可能耗时较长
- 前端需要看到任务状态,而不是一直假 loading
用什么技术
- Azure Service Bus:异步任务投递
- PostgreSQL:任务状态持久化
- Redis:缓存短状态
- SSE / 轮询:状态回传给前端
怎么落地
- 新增表:
async_tasksidtask_typeconversation_idmessage_idstatusprogress_textresult_payloadcreated_atupdated_at
- 新增接口:
GET /api/tasks/{id}
- 第一阶段先采用“数据库状态 + 前端轮询”
- 后续再增强为 SSE 任务事件推送
15.10 扩展连接状态注入 graph
要完成什么
- 某个扩展是否已连接,必须直接决定 graph 中哪些工具可用
- 未连接扩展不能被调用
- 已连接扩展才能参与 agent 路由
用什么技术
- extension registry
- LangGraph state injection
- tool availability resolver
怎么落地
- graph 执行前先加载当前扩展连接状态
- 注入 state:
{
"available_extensions": ["ticket"]
}
- router 节点判断:
- 工单问题 + ticket 已连接 -> 允许调用
- 工单问题 + ticket 未连接 -> 返回“扩展未连接”
- 销售 / 云管未来直接复用该机制
15.11 会话重命名 / 置顶等预留
要完成什么
- 为左侧会话更多操作菜单预留后端能力
- 支持未来扩展:
- 重命名
- 置顶
- 自定义排序
用什么技术
- PostgreSQL conversation metadata
- 排序字段 / pinned 字段
怎么落地
- conversations 表补充字段:
custom_titlepinnedsort_order
- 接口统一走:
PATCH /api/conversations/{id}
- 即使前端暂未开放置顶,也建议先预留字段
15.12 会话级偏好元数据
要完成什么
- 记录会话偏好信息,例如:
- 当前选中的模型
- 当前启用工具
- 默认搜索模式
- 当前关联扩展
- 会话恢复时自动延续这些设置
用什么技术
- PostgreSQL JSON metadata
- LangGraph state hydration
怎么落地
- conversations 表增加:
metadata_json
- 典型结构示例:
{
"selected_model": "gpt-5.4",
"selected_mode": "pro",
"enabled_tools": ["knowledge", "search"],
"preferred_search_mode": "deep"
}
- 会话恢复时把 metadata 注入 graph 初始 state
16. 接口层总表
虽然本方案不以 FastAPI 为重点,但前端要接入,仍然需要有 HTTP/SSE 出口。这里把它视为“接入层”,不是方案核心。
第一阶段建议建设的接口
基础接口
GET /health
会话接口
GET /api/conversationsPOST /api/conversationsGET /api/conversations/{id}PATCH /api/conversations/{id}DELETE /api/conversations/{id}
聊天接口
POST /api/chat/stream
工单接口
GET /api/tickets/summaryGET /api/ticketsGET /api/tickets/{id}
搜索接口
POST /api/search/internalPOST /api/search/external
文档接口
POST /api/documents/generateGET /api/documents/{task_id}
附件接口
POST /api/attachmentsGET /api/attachments/{id}
沙盒接口
POST /api/sandbox/run
16. 推荐技术组合总结
核心框架
- LangChain:模型调用、Prompt 组织、Tool 封装、Memory 适配
- LangGraph:对话状态机、工具路由、任务编排、长链路执行
数据层
- PostgreSQL:会话/消息/工具调用/任务持久化
- Redis:缓存、短状态、限流
- Azure Blob Storage:附件、产物、文档存储
- Azure Service Bus:异步任务编排
- SQLAlchemy / SQLModel:ORM
- Alembic:迁移管理
AI 与搜索
- Azure OpenAI:LLM 生成与总结
- KB_AGENT:内部知识库检索
- Jina MCP SSE / v1 + Search / Reader / Rerank:外部搜索链路
外部业务系统
- Gongdan API:工单只读
- Doc Creator Agent:文档生成
- Daytona Sandbox:受控代码执行
协议与接入
- SSE:流式输出到前端
- HTTP API:前端接入层
17. 第一阶段开发顺序
第一步
先完成:
- LangChain + LangGraph 基础工程
- PostgreSQL 接入
- conversations/messages 表
- 基础聊天 graph
/api/chat/stream/api/conversations
第二步
接入:
- Azure OpenAI
- KB_AGENT tool
- 工单 tools
第三步
接入:
- Jina MCP SSE / v1 搜索链路
- Search / Reader / Rerank tool chain
- 来源引用
- graph 中间状态流式事件
- Redis 缓存
第四步
接入:
- 文档生成 tool
- 附件解析 loader
- sandbox tools
- Azure Blob Storage
- Azure Service Bus
- graph 持久化和恢复
18. 最终结论
这个项目当前最合适的后端方案,如果明确要求基于 LangChain 框架来做,那就应该是:
- 用 LangChain + LangGraph 做整个后端核心
- 用 Azure OpenAI 做模型生成和总结
- 用 KB_AGENT 做内部知识检索工具
- 用 Jina Search/Reader/Rerank 做外部搜索工具链
- 用 Gongdan API 做工单查询工具
- 用 Doc Creator Agent 做正式文档生成工具
- 用 Daytona Sandbox 做受控执行工具
- 用 PostgreSQL 做会话、消息、任务和 graph 状态持久化
- 用 Redis 做缓存和短状态管理
- 用 Azure Blob Storage 做附件与产物存储
- 用 Azure Service Bus 做长任务异步编排
- 用 MCP 方式 标准化接入 Jina 外部搜索
整个系统本质上是: 一个基于 LangGraph 编排、具备缓存/存储/异步任务能力的企业级对话 Agent 后端。
而且整个过程中: 前端交互不改,只替换数据来源和后端能力。