Enhance LLM integration by adding OpenAI client support and enabling dynamic routing between DeepSeek and OpenAI services. Update environment configuration to include LLM_SERVICE_CODE for service selection, and modify API server to accommodate new request parameters for language and model. Implement streaming response improvements for chat interactions, allowing for segmented SSE output. Update documentation and impact analysis to reflect these changes.
This commit is contained in:
陈辅元
@@ -42,6 +42,121 @@
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — 新增 OpenAI LLM Client（对话/JSON 输出）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：补齐 `backend/llm/openai_client.py`，提供 OpenAI（或 OpenAI 兼容网关）调用封装，支持同步/异步 `chat` 与 `chat_with_json`，便于与既有 prompt/JSON 输出链路复用。
|
||||
- **涉及模块**：`backend/llm/openai_client.py`、`.env`（仅补充注释示例，不影响现有运行配置）。
|
||||
- **改动类型**：功能新增。
|
||||
|
||||
## 2. 方法级改动分析
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `OpenAIClient.chat` | 新增：基于 `openai` SDK 的 Chat Completions 调用封装，支持覆盖 `temperature/max_tokens/top_p` 等参数。 |
|
||||
| `OpenAIClient.chat_with_json` | 新增：抽取/解析 JSON（兼容 markdown code fence）；解析失败时返回 `{"_json_decode_failed": true, "raw_content": ...}`。 |
|
||||
| `create_openai_client` | 新增：从环境变量读取 `OPENAI_API_KEY`、可选 `OPENAI_BASE_URL`、`OPENAI_MODEL/OPENAI_CHAT_MODEL`。 |
|
||||
|
||||
## 3. 调用方与影响范围分析
|
||||
|
||||
- **调用方**：当前仓库运行链路仍默认使用 `DeepSeekClient`；本次新增仅提供可选能力，未修改既有编排器/接口路由。
|
||||
- **破坏性变更**：否。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：低（新增模块，不改变既有默认路径）。
|
||||
- **回滚**：删除新增文件与对应文档/注释即可。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 验证与测试
|
||||
|
||||
- 已执行：`python -m py_compile backend/llm/openai_client.py`。
|
||||
|
||||
## 6. 配置变更
|
||||
|
||||
- `.env`：补充 `OPENAI_MODEL/OPENAI_CHAT_MODEL` 注释示例（不修改现有真实配置）。
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — DeepSeek/OpenAI 双模型切换（LLM_SERVICE_CODE）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：支持在 DeepSeek 与 OpenAI（或兼容网关）之间切换 LLM 调用来源，便于在不同环境/配额下切换推理服务。
|
||||
- **涉及模块**：`backend/llm/router.py`（新）、`backend/agents/orchestrator.py`、`backend/main.py`、`api_server.py`、`.env`（新增开关）。
|
||||
- **改动类型**：功能增强（可配置路由）。
|
||||
|
||||
## 2. 方法级改动分析
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `backend/llm/router.py` | 新增：`resolve_llm_service_code` + `create_llm_client`，按 `LLM_SERVICE_CODE` 或 Key 存在性创建 LLM Client。 |
|
||||
| `Text2SQLOrchestrator.__init__` | 新增可选 `llm_client` 参数；若传入则作为 `self.deepseek` 使用（保留属性名避免大范围改动）。 |
|
||||
| `backend/main.py` | `setup_environment` 增加 `LLM_SERVICE_CODE` 校验；`create_orchestrator` 通过 router 创建 LLM Client。 |
|
||||
| `api_server.py` | 错误提示文案更新；编排器初始化保持通过 `create_orchestrator` 完成。 |
|
||||
|
||||
## 3. 调用方与影响范围分析
|
||||
|
||||
- **调用方**：CLI（`backend/main.py`）与 API（`api_server.py`）初始化编排器路径。
|
||||
- **行为变化**：
|
||||
- `LLM_SERVICE_CODE=openai`：使用 `OPENAI_*` 做 LLM 调用（意图分类 / 归一 / 选表 / 生成 / 说明等）。
|
||||
- `LLM_SERVICE_CODE=deepseek` 或未设置但存在 `DEEPSEEK_API_KEY`：仍默认 DeepSeek（与历史一致）。
|
||||
- **破坏性变更**：否（对外 API 入参/出参不变；仅初始化与内部客户端来源可切换）。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：中（不同模型对 JSON 严格性/输出格式偏好不同，可能影响 `chat_with_json` 的解析成功率与稳定性；失败时仍会返回 `_json_decode_failed` 供上游处理）。
|
||||
- **回滚**：将 `LLM_SERVICE_CODE` 切回 `deepseek` 或回退相关文件改动。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 验证与测试
|
||||
|
||||
- 已执行：`python -m py_compile` 覆盖 `backend/llm/router.py`、`backend/agents/orchestrator.py`、`backend/main.py`、`api_server.py`。
|
||||
|
||||
## 6. 配置变更
|
||||
|
||||
| 配置项 | 含义 | 取值 |
|
||||
|--------|------|------|
|
||||
| `LLM_SERVICE_CODE` | 选择 LLM 路由 | `openai` / `deepseek`（留空自动按 Key 选择，优先 deepseek） |
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — 适配前端参数（lang_code / model）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：前端请求会携带 `lang_code`（`zh`/`tc`/`en`）与 `model`（模型名覆盖）；后端需接收并在对话分支/LLM 调用侧生效。
|
||||
- **涉及模块**：`api_server.py`。
|
||||
- **改动类型**：兼容性增强。
|
||||
|
||||
## 2. 方法级改动分析
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `NLChatRequest` | 新增 `model` 字段；保留 `lang_code`（规范化为 `zh/tc/en/auto`）。 |
|
||||
| `nl_chat` / `_chat_stream_events` | 对话分支：空输入/默认引导文案按 `lang_code` 返回（中/繁/英）。 |
|
||||
| `_maybe_override_orch_llm`（新） | 若请求带 `service_code/model`，临时覆盖 `orchestrator.deepseek` 为按请求创建的 LLM client；使用锁避免并发串改。 |
|
||||
| `_run_generate` | 增加 `request` 参数，用于按请求覆盖 LLM client 后再生成。 |
|
||||
|
||||
## 3. 调用方与影响范围分析
|
||||
|
||||
- **调用方**：`/g3sb/api/nl/chat`、`/g3sb/api/nl/chat/stream`。
|
||||
- **破坏性变更**：否（仅新增可选请求字段与内部适配；未提供时行为保持不变）。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：中（带 `model/service_code` 的请求会串行化执行 LLM 调用，避免并发污染；在高并发时可能降低吞吐）。
|
||||
- **回滚**：回退 `api_server.py` 的按请求覆盖逻辑即可。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 验证与测试
|
||||
|
||||
- 已执行：`python -m py_compile api_server.py`。
|
||||
|
||||
# Impact Analysis Report — 方案A：新话题禁用 dialog_context（防上下文污染）
|
||||
|
||||
## 1. 改动概览
|
||||
@@ -409,3 +524,30 @@
|
||||
## 4. 配置
|
||||
|
||||
| `FEWSHOT_CHROMA_EPHEMERAL` | 可选；`true` 时与旧版「仅内存」行为一致。 |
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — `/g3sb/api/nl/chat/stream` 分片 SSE（追加）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：前端 `chatStore` 按多次 `{ stage, stream_kind, content }` 累加 `chatText` / `sqlGenHtml`；原先后端在 `chat` / `sql_gen` 阶段各只发一条大包，网络侧无渐进感。
|
||||
- **涉及模块**：`api_server.py`。
|
||||
- **改动类型**：行为优化（SSE 事件形态不变，仅增加条数）。
|
||||
|
||||
## 2. 方法级改动
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `_sse_stream_text_chunks` | 新增：按字符窗口（默认 64，可用 `SSE_STREAM_CHUNK_CHARS` 覆盖）拆成多段 SSE；段间 `asyncio.sleep(0)` 让出事件循环。 |
|
||||
| `_chat_stream_events` | `chat` / `sql_gen` 正文改为 `async for` 分片 `yield`。 |
|
||||
|
||||
## 3. 破坏性变更
|
||||
|
||||
- **否**（结束包 `code/msg/data` 仍与原先一致）。
|
||||
|
||||
## 4. 配置变更
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| `SSE_STREAM_CHUNK_CHARS` | 可选；每段 SSE 的 `content` 最大字符数，默认 `64`。 |
|
||||
|
||||
Reference in New Issue
Block a user