langchain-learning-kit/QUICKSTART.md

快速开始指南 (Conda 环境)

🚀 一键安装（推荐）

第一步: 运行安装脚本

双击 setup_conda_env.bat 文件，脚本会自动：

• 创建 conda 环境 (Python 3.11)
• 安装所有依赖包
• 验证安装结果

第二步: 验证环境

# 激活环境
conda activate pyth-311

# 运行验证脚本
python verify_env.py

如果所有检查通过，说明环境配置成功！✅

---

📋 详细步骤

1. 配置环境变量

确保 .env 文件已配置（你已经完成✅）：

DATABASE_URL=mysql+pymysql://root:123456@localhost:3306/langchain_learning
OPENAI_API_KEY=sk-your-key-here
OPENAI_BASE_URL=https://api.openai-proxy.org/v1

注意: 如果使用 OpenAI 代理或转发服务，请配置 OPENAI_BASE_URL

2. 确保 MySQL 运行

# 检查 MySQL 是否运行
mysql -u root -p123456 -e "SHOW DATABASES;"

# 如果数据库不存在，创建它
mysql -u root -p123456 -e "CREATE DATABASE langchain_learning CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

3. 初始化数据库

# 激活 conda 环境
conda activate pyth-311

# 进入 app 目录
cd app

# 执行数据库迁移
alembic upgrade head

成功后会创建 6 张表：

• ✅ models (模型配置)
• ✅ knowledge_bases (知识库)
• ✅ documents (文档)
• ✅ conversations (会话)
• ✅ messages (消息)
• ✅ tool_calls (工具调用)

4. 验证数据库表

mysql -u root -p123456 langchain_learning -e "SHOW TABLES;"

应该看到上述 6 张表。

---

✅ 环境配置完成检查清单

• Conda 环境创建: conda activate pyth-311
• 依赖安装完成: python verify_env.py 全部通过
• .env 文件已配置
• MySQL 服务运行中
• 数据库 langchain_learning 已创建
• 数据库表已迁移 (6张表)
• OpenAI API Key 已配置

---

🎯 下一步

环境配置完成后，有两个选择：

选择 A: 等待剩余代码实现

目前完成度约 30%，还需要实现：

• 服务层 (KBManager, ConvManager, AgentOrchestrator)
• API 层 (4组端点)
• FastAPI 主程序

查看 TODO_pyth-311.md 了解详细待办事项。

选择 B: 测试已完成的模块

# 激活环境
conda activate pyth-311

# 进入项目目录
cd C:\work\workspace\PycharmProjects\study-work\pyth-311

# 测试配置加载
python -c "from app.config import get_settings; print(get_settings())"

# 测试数据库连接
python -c "from app.db.session import init_db_manager; from app.config import get_settings; db = init_db_manager(get_settings()); print('Database connected!')"

# 测试 ModelManager
python -c "from app.services.model_manager import ModelManager; print('ModelManager imported successfully!')"

---

🔧 常见问题

Q1: conda 命令未找到

解决方案:

1. 确保 Anaconda 已安装
2. 重启命令行工具
3. 或手动添加 conda 到 PATH

Q2: 环境创建失败 - "Solving environment: failed"

解决方案:

# 方式 1: 删除旧环境重试
conda env remove -n pyth-311
conda env create -f environment.yml

# 方式 2: 使用国内镜像源
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --set show_channel_urls yes
conda env create -f environment.yml

Q3: MySQL 连接失败

检查清单:

1. MySQL 服务是否运行: services.msc 查看 MySQL 服务
2. 端口是否正确: 默认 3306
3. 用户名密码是否正确: root / 123456
4. 数据库是否存在: SHOW DATABASES;

Q4: Alembic 迁移失败

解决方案:

# 检查 alembic.ini 配置
cd src
cat alembic.ini

# 手动创建表（备选方案）
python scripts/init_db.py

Q5: FAISS 安装失败

解决方案:

# Windows 确保安装 CPU 版本
pip install faiss-cpu==1.7.4

---

📚 相关文档

• CONDA_SETUP.md - 详细的 Conda 环境配置说明
• README.md - 完整的项目文档
• TODO_pyth-311.md - 待办事项清单
• IMPLEMENTATION_STATUS.md - 当前实现状态

---

💡 提示

1. 始终激活环境: 每次开发前运行 conda activate pyth-311
2. 使用验证脚本: 遇到问题先运行 python verify_env.py 检查
3. 查看日志: 遇到错误查看详细的错误信息
4. 保持依赖更新: 定期运行 conda env update -f environment.yml --prune

---

环境配置完成！🎉

如有问题，请查看 CONDA_SETUP.md 或提交 Issue。