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

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

# 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 (精简后)

provider: openai
openai:
  base_url: "..."
  api_key: "..."
  model: "deepseek-chat"

retrieval:
  endpoint: "..."
  api_key: "..."

# 其他非LLM配置...

🔧 代码变更

新增配置模型

• LLMParametersConfig: LLM参数配置
• LLMPromptsConfig: 提示词配置
• LLMPromptConfig: 完整的LLM提示配置

增强的配置加载

# 支持加载两个配置文件
config = Config.from_yaml("config.yaml", "llm_prompt.yaml")

# 新的方法
config.get_max_context_length()  # 统一的上下文长度获取

向后兼容性

• 如果llm_prompt.yaml不存在，系统将回退到config.yaml中的旧配置
• 现有的llm.rag配置仍然被支持

🚀 使用方法

开发环境

# 确保两个配置文件都存在
ls config.yaml llm_prompt.yaml

# 启动服务 (自动加载两个文件)
uv run python service/main.py

配置更新

# 加载配置时指定文件路径
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格式正确性
• 检查必需字段是否存在
• 查看日志获取详细错误信息

这个配置分离为未来的功能扩展和维护提供了更好的基础。