构建最小可运行 LangGraph 程序,具备基础输入输出与配置读取能力。

• ✅ 构建基础 State 结构
• ✅ 搭建 base_graph.py(含输入与回显节点)
• ✅ 统一读取 .env 与 configs/dev.yaml
• ✅ 基础图结构: parse_intent → echo → END

rookie-nl2sql/
├── graphs/
│   ├── state.py           # State 定义
│   └── base_graph.py      # 基础图实现
├── configs/
│   ├── config.py          # 配置加载器
│   └── dev.yaml           # 开发环境配置
├── .env.example           # 环境变量模板
├── requirements.txt       # 依赖清单
└── README.md             # 项目说明

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件,选择一个 LLM 提供商并填入 API Key
# 注意: M0 阶段不需要 API Key,可以留空。M1 开始需要配置。

支持的 LLM 提供商 (推荐国内用户使用 DeepSeek 或 Qwen):

• DeepSeek (推荐): 性价比高,国内访问快 - 获取 API Key
• Qwen (通义千问): 阿里云生态 - 获取 API Key
• OpenAI (可选): 需要科学上网

配置示例 (.env 文件):

# 使用 DeepSeek (推荐)
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 或使用 Qwen
# LLM_PROVIDER=qwen
# QWEN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

详细配置说明请查看: docs/LLM_CONFIG_GUIDE.md

# 测试配置加载
python configs/config.py

# 运行基础图测试
python graphs/base_graph.py

输入一句话,控制台能正确打印意图对象。

==================================================
Starting NL2SQL Graph (M0 - Scaffold)
==================================================

=== Parse Intent Node ===
Question: 查询所有用户的订单数量
Intent: {
  "type": "query",
  "question_length": 13,
  "has_keywords": true,
  "parsed_at": "2024-01-15T10:30:00"
}

=== Echo Node ===
Session ID: 550e8400-e29b-41d4-a716-446655440000
Question: 查询所有用户的订单数量
Intent: {
  "type": "query",
  "question_length": 13,
  "has_keywords": true,
  "parsed_at": "2024-01-15T10:30:00"
}
Timestamp: 2024-01-15T10:30:00.123456

Final State Keys: ['question', 'session_id', 'timestamp', 'intent']
Intent Parsed: ✓

class NL2SQLState(TypedDict):
    question: str              # 用户问题
    timestamp: Optional[str]   # 时间戳
    session_id: Optional[str]  # 会话ID
    intent: Optional[Dict]     # 意图对象

• parse_intent_node: 解析用户意图,提取基础信息
• echo_node: 回显当前状态,用于验证

• 支持从 .env 和 dev.yaml 读取配置
• 支持点号访问嵌套配置 (如 config.get('llm.model'))
• 环境变量优先级高于 YAML 配置

• M1 (01-prompt-nl2sql): 使用提示词工程让 LLM 生成 SQL
• M2 (02-func-call-db): 通过 Function Call 执行数据库操作
• M3 (03-schema-ingestion): 引入数据库 Schema 感知

在 parse_intent_node 中添加更多意图分析:

• 检测问题类型 (统计/查询/排序)
• 提取关键词 (表名、字段名等)

创建一个新的 log_node,记录每次查询的基础信息到文件。

修改 dev.yaml,添加自定义配置项,并在代码中读取验证。

Q: 运行时提示 ModuleNotFoundError? A: 确保已安装所有依赖: pip install -r requirements.txt

Q: 配置文件找不到? A: 检查工作目录是否在项目根目录,或使用绝对路径。

Q: M0 需要 OpenAI API Key 吗? A: 不需要。M0 只验证基础框架,不调用 LLM。M1 开始需要。

• LangGraph: 状态图编排框架
• LangChain: LLM 应用开发框架
• Python-dotenv: 环境变量管理
• PyYAML: YAML 配置解析

MIT License