init

vw-agentic-rag/docs/topics/LLM_CONFIG_SEPARATION.md

@@ -0,0 +1,124 @@
+# LLM Configuration Separation Guide
+
+## 📋 Overview
+
+为了更好地组织配置文件并提高可维护性，我们将LLM相关的参数和提示词模板从主配置文件中分离出来，放到专门的`llm_prompt.yaml`文件中。
+
+## 🎯 配置文件结构
+
+### 主配置文件: `config.yaml`
+包含应用的核心配置：
+- Provider设置 (OpenAI/Azure)
+- 检索端点配置
+- 数据库连接信息
+- 应用设置
+- 日志配置
+
+### LLM配置文件: `llm_prompt.yaml`
+包含LLM相关的所有配置：
+- LLM参数 (temperature, max_context_length等)
+- 提示词模板 (agent_system_prompt等)
+
+## 📂 文件示例
+
+### `llm_prompt.yaml`
+```yaml
+# LLM Parameters and Prompt Templates Configuration
+parameters:
+  temperature: 0
+  max_context_length: 96000
+
+prompts:
+  agent_system_prompt: |
+    You are an Agentic RAG assistant...
+    # 完整的提示词内容
+```
+
+### `config.yaml` (精简后)
+```yaml
+provider: openai
+openai:
+  base_url: "..."
+  api_key: "..."
+  model: "deepseek-chat"
+
+retrieval:
+  endpoint: "..."
+  api_key: "..."
+
+# 其他非LLM配置...
+```
+
+## 🔧 代码变更
+
+### 新增配置模型
+- `LLMParametersConfig`: LLM参数配置
+- `LLMPromptsConfig`: 提示词配置  
+- `LLMPromptConfig`: 完整的LLM提示配置
+
+### 增强的配置加载
+```python
+# 支持加载两个配置文件
+config = Config.from_yaml("config.yaml", "llm_prompt.yaml")
+
+# 新的方法
+config.get_max_context_length()  # 统一的上下文长度获取
+```
+
+### 向后兼容性
+- 如果`llm_prompt.yaml`不存在，系统将回退到`config.yaml`中的旧配置
+- 现有的`llm.rag`配置仍然被支持
+
+## 🚀 使用方法
+
+### 开发环境
+```bash
+# 确保两个配置文件都存在
+ls config.yaml llm_prompt.yaml
+
+# 启动服务 (自动加载两个文件)
+uv run python service/main.py
+```
+
+### 配置更新
+```python
+# 加载配置时指定文件路径
+from service.config import load_config
+config = load_config("config.yaml", "llm_prompt.yaml")
+
+# 获取LLM参数
+llm_config = config.get_llm_config()
+prompts = config.get_rag_prompts()
+max_length = config.get_max_context_length()
+```
+
+## ✅ 优势
+
+1. **关注点分离**: LLM配置与应用配置分离
+2. **更好的可维护性**: 提示词变更不影响其他配置
+3. **版本控制友好**: 可以独立管理提示词版本
+4. **团队协作**: 不同角色可以专注于不同的配置文件
+5. **向后兼容**: 不破坏现有的配置结构
+
+## 📝 迁移指南
+
+如果你有现有的`config.yaml`文件包含LLM配置：
+
+1. **创建`llm_prompt.yaml`**: 将`llm.rag`部分移动到新文件
+2. **更新`config.yaml`**: 移除`llm`配置段
+3. **测试**: 确保应用正常加载两个配置文件
+
+系统会自动处理配置优先级：`llm_prompt.yaml` > `config.yaml`中的`llm`配置 > 默认值
+
+## 🔧 故障排除
+
+### 配置文件未找到
+- 确保`llm_prompt.yaml`与`config.yaml`在同一目录
+- 检查文件权限和格式是否正确
+
+### 配置加载失败
+- 验证YAML格式正确性
+- 检查必需字段是否存在
+- 查看日志获取详细错误信息
+
+这个配置分离为未来的功能扩展和维护提供了更好的基础。