socweb/gpthd.md

SOC 项目后端功能方案（按功能拆解）

约束：在未获得明确允许前，不修改前端交互，只补后端能力、接口和数据层。 目标：严格围绕当前 ~/go/soc 这个 Gemini 风格前端，为每一个功能明确说明“用什么技术，完成什么功能，怎么落地”。

---

1. 对话流式回复

要完成什么功能

• 用户在当前聊天输入框发送消息
• 后端实时返回回答内容
• 支持“思考中 / 检索中 / 生成中”的流式状态
• 不改变现有前端交互，只替换当前前端 simulateAIResponse()

用什么技术

• FastAPI：提供聊天接口
• SSE（Server-Sent Events）：把大模型回答流式推给前端
• Azure OpenAI：生成最终回答
• PostgreSQL：保存消息记录和会话记录

怎么落地

• 新增接口：POST /api/chat/stream
• 前端发送用户消息到后端
• 后端先写入用户消息
• 再调用 Azure OpenAI 流式生成
• 将生成过程通过 SSE 持续返回给前端
• 最终把 assistant 回复保存入库

输出结果

• 前端保持当前 Gemini 风格交互不变
• 用户发送后能看到真实流式回答
• 替换掉前端 mock 返回逻辑

---

2. 会话管理

要完成什么功能

• 左侧历史会话列表从真实数据读取
• 支持新建会话
• 支持切换会话
• 支持删除会话
• 支持自动生成会话标题

用什么技术

• FastAPI：提供 REST API
• PostgreSQL：保存 conversation 和 message
• SQLAlchemy / SQLModel：管理数据表和查询

怎么落地

• 新增接口：
  • GET /api/conversations
  • POST /api/conversations
  • GET /api/conversations/{id}
  • PATCH /api/conversations/{id}
  • DELETE /api/conversations/{id}
• 用户首次发送消息时自动创建会话
• 默认用首条消息前 20~30 字生成标题
• 前端左侧栏改为读取真实会话数据

输出结果

• 当前左侧 mock 会话列表替换成数据库真实数据
• 用户聊天记录可恢复

---

3. 内部知识库检索

要完成什么功能

• 当用户提问产品、方案、配置、内部资料时
• 后端优先查询内部知识库
• 再把知识库结果交给大模型总结回答
• 回答中带来源信息

用什么技术

• KB_AGENT 接口：调用内部知识库搜索
• FastAPI service layer：封装知识库调用
• Azure OpenAI：对检索结果总结与生成回答

怎么落地

• 新增服务模块：kb_agent.py
• 根据 EXTERNAL_SERVICES.md 中的：
  • KB_AGENT_URL
  • KB_AGENT_API_KEY
  • KB_AGENT_SEARCH_PATH
• 后端在识别为内部知识问题时：
  1. 请求知识库搜索
  2. 获取 top-k 文档片段
  3. 做摘要裁剪
  4. 将结果作为上下文交给 Azure OpenAI
• 前端不改交互，只在回答里附带引用来源块

输出结果

• 当前产品类问题不再纯靠大模型空想
• 回答能基于内部知识库
• 更适合售前、售后、研发支持场景

---

4. 外部 AI 搜索

要完成什么功能

• 当用户问实时互联网信息、行业动态、外部资料时
• 后端自动执行外部搜索
• 支持网页搜索、内容读取、结果重排
• 满足快速模式和深度模式
• 后续支持图片和视频结果展示

用什么技术

• Jina Search API：做外部搜索
• Jina Reader：读取网页正文
• Rerank 模型：对结果重排
• Azure OpenAI：基于外部资料生成答案

怎么落地

• 新增模块：
  • jina_search.py
  • jina_reader.py
  • reranker.py
• 固定流程：
  • Search -> Read -> Rerank -> LLM
• 提供三种模式：
  • fast：低延迟，少量搜索
  • deep：高质量，多轮检索
  • auto：后端自动判断
• 前端仍保持原有聊天区交互，只增加来源区块展示

输出结果

• 外部问题可获得更准确结果
• 不再只依赖大模型参数知识
• 满足企业级搜索准确度要求

---

5. 工单系统只读接入

要完成什么功能

• 支持查询工单列表
• 支持查询工单详情
• 支持汇总最近高优先级工单
• 支持在聊天中回答“最近有什么 P0/P1 工单”“某类问题集中在哪里”
• 支持首页/聊天区展示工单摘要数据

用什么技术

• Gongdan HTTP API：工单数据来源
• FastAPI：对前端提供统一工单接口
• PostgreSQL（可选缓存）：保存摘要缓存或查询记录
• Azure OpenAI：对工单数据做归纳总结

怎么落地

• 新增模块：gongdan_client.py
• 新增接口：
  • GET /api/tickets/summary
  • GET /api/tickets
  • GET /api/tickets/{id}
• 对话场景下：
  • 用户问工单问题
  • 后端查询 gongdan
  • 将结果整理后交给大模型总结
• 非对话场景下：
  • 前端通过 summary 接口读取摘要

输出结果

• 当前前端 mock 工单摘要可替换为真实工单数据
• 用户能直接在聊天里分析工单问题

---

6. 文档生成

要完成什么功能

• 用户在聊天中要求生成方案、汇报、纪要、总结
• 后端把需求提交给文档生成 Agent
• 返回任务状态
• 文档完成后可返回下载地址或结果卡片

用什么技术

• Doc Creator Agent HTTP API：生成正式文档
• FastAPI BackgroundTasks / 异步任务机制：管理任务状态
• PostgreSQL：保存文档任务记录
• Azure OpenAI：前置整理文档提纲或结构

怎么落地

• 新增接口：
  • POST /api/documents/generate
  • GET /api/documents/{task_id}
• 对话中识别“生成文档”类意图
• 后端创建任务记录
• 调用 doc creator agent
• 前端保持当前聊天交互，后续只在消息中增加文档结果卡片

输出结果

• 用户可从聊天直接发起正式文档生成
• 满足销售、售前、汇报场景

---

7. 沙盒代码执行

要完成什么功能

• 处理表格、JSON、日志、数据分析类任务
• 允许后端在安全沙盒中执行代码
• 返回执行结果、图表、文件
• 不直接改前端交互，只把结果作为消息内容或附件返回

用什么技术

• Daytona Sandbox：安全执行环境
• FastAPI：封装沙盒执行入口
• Python 工具链：pandas / matplotlib / json / csv 等
• PostgreSQL：记录执行任务

怎么落地

• 新增接口：POST /api/sandbox/run
• 第一阶段不开放任意代码执行
• 先封装几类固定能力：
  • CSV 汇总
  • JSON 转换
  • 数据统计
  • 图表生成
• 对话编排层按意图决定是否调用 sandbox

输出结果

• 数据分析、表格处理能力可真正执行
• 后端具备“算”的能力，而不只是“说”的能力

---

8. 附件上传与解析

要完成什么功能

• 用户上传文件后，后端能接收附件
• 保存附件元数据
• 提取文本内容供知识理解、搜索或分析使用
• 后续支持文档总结、数据分析、代码执行

用什么技术

• FastAPI UploadFile：接收文件
• 对象存储/本地文件存储：保存附件
• 文本解析库：PDF、DOCX、TXT、CSV 解析
• PostgreSQL：保存附件元数据

怎么落地

• 新增接口：
  • POST /api/attachments
  • GET /api/attachments/{id}
• 后端保存文件路径与文件类型
• 针对不同格式做解析
• 将解析文本挂到对应消息上下文里

输出结果

• 后续聊天可真正支持“基于附件分析”
• 为文档生成、沙盒分析、知识问答提供基础能力

---

9. 工具编排层

要完成什么功能

• 判断用户问题该调用哪个能力
• 决定先查 KB、还是先查工单、还是先外部搜索
• 决定是否进入文档生成或沙盒执行
• 把多个工具结果统一整理成大模型上下文

用什么技术

• Python Orchestrator：自定义编排逻辑
• Azure OpenAI：辅助做工具选择与结果总结
• FastAPI service layer：承接 API 和工具层

怎么落地

• 新增模块：
  • planner.py
  • chat_orchestrator.py
  • context_builder.py
• 第一阶段可以先做规则驱动：
  • 问产品/项目 -> KB
  • 问实时外部信息 -> Search
  • 问工单 -> Tickets
  • 问生成汇报 -> Documents
  • 问数据处理 -> Sandbox
• 第二阶段再逐步引入 LLM 辅助路由

输出结果

• 后端从“多个孤立接口”升级成“统一智能后端”
• 前端仍然只需要一个对话入口

---

10. 数据持久化

要完成什么功能

• 保存历史会话
• 保存聊天消息
• 保存工具调用记录
• 保存附件记录
• 保存文档任务记录

用什么技术

• PostgreSQL：主数据库
• SQLAlchemy / SQLModel：ORM
• Alembic：数据库迁移

怎么落地

• 至少建立以下表：
  • conversations
  • messages
  • tool_runs
  • attachments
  • document_tasks
• 以后如需多租户，再增加：
  • users
  • organizations
  • memberships
  • audit_logs

输出结果

• 数据不丢失
• 会话可追溯
• 工具调用过程可排查

---

11. 接口层总表

第一阶段建议建设的接口

基础接口

• GET /health

会话接口

• GET /api/conversations
• POST /api/conversations
• GET /api/conversations/{id}
• PATCH /api/conversations/{id}
• DELETE /api/conversations/{id}

聊天接口

• POST /api/chat/stream

工单接口

• GET /api/tickets/summary
• GET /api/tickets
• GET /api/tickets/{id}

搜索接口

• POST /api/search/internal
• POST /api/search/external

文档接口

• POST /api/documents/generate
• GET /api/documents/{task_id}

附件接口

• POST /api/attachments
• GET /api/attachments/{id}

沙盒接口

• POST /api/sandbox/run

---

12. 推荐技术组合总结

基础后端框架

• FastAPI：API 服务
• Uvicorn / Gunicorn：服务运行

数据层

• PostgreSQL：数据持久化
• SQLAlchemy / SQLModel：ORM
• Alembic：迁移管理

AI 与搜索

• Azure OpenAI：LLM 生成与总结
• KB_AGENT：内部知识库检索
• Jina Search / Reader / Rerank：外部搜索链路

外部业务系统

• Gongdan API：工单只读
• Doc Creator Agent：文档生成
• Daytona Sandbox：受控代码执行

交互协议

• SSE：流式输出
• REST API：管理类接口

---

13. 第一阶段开发顺序

第一步

先完成：

• FastAPI 基础框架
• PostgreSQL 接入
• conversations/messages 表
• /api/chat/stream
• /api/conversations

第二步

接入：

• Azure OpenAI
• KB_AGENT
• 工单系统

第三步

接入：

• Jina 外部搜索
• 来源引用
• 工具状态流式事件

第四步

接入：

• 文档生成任务
• 附件解析
• Sandbox

---

14. 最终结论

这个项目当前最合适的后端建设方式，不是泛泛而谈“做一个 AI 平台后端”，而是严格按功能拆：

• 用 FastAPI + SSE 完成真实聊天流式回复
• 用 PostgreSQL 完成会话和消息持久化
• 用 Azure OpenAI 完成回答生成
• 用 KB_AGENT 完成内部知识检索
• 用 Jina Search/Reader/Rerank 完成外部搜索
• 用 Gongdan API 完成工单只读分析
• 用 Doc Creator Agent 完成正式文档生成
• 用 Daytona Sandbox 完成安全数据处理与代码执行

而且整个过程中： 前端交互不改，只替换数据来源和后端能力。