langchain-learning-kit/QUICKSTART.md

# 快速开始指南 (Conda 环境)

## 🚀 一键安装（推荐）

### 第一步: 运行安装脚本

双击 **`setup_conda_env.bat`** 文件，脚本会自动：
- 创建 conda 环境 (Python 3.11)
- 安装所有依赖包
- 验证安装结果

### 第二步: 验证环境

```bash
# 激活环境
conda activate pyth-311

# 运行验证脚本
python verify_env.py
```

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

---

## 📋 详细步骤

### 1. 配置环境变量

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

```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 运行

```bash
# 检查 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. 初始化数据库

```bash
# 激活 conda 环境
conda activate pyth-311

# 进入 app 目录
cd app

# 执行数据库迁移
alembic upgrade head
```

成功后会创建 6 张表：
- ✅ models (模型配置)
- ✅ knowledge_bases (知识库)
- ✅ documents (文档)
- ✅ conversations (会话)
- ✅ messages (消息)
- ✅ tool_calls (工具调用)

### 4. 验证数据库表

```bash
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: 测试已完成的模块

```bash
# 激活环境
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"

**解决方案**:
```bash
# 方式 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 迁移失败

**解决方案**:
```bash
# 检查 alembic.ini 配置
cd src
cat alembic.ini

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

### Q5: FAISS 安装失败

**解决方案**:
```bash
# 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。