langchain-learning-kit/CONDA_SETUP.md

# Conda 环境配置指南

## 快速开始

### 方式 1: 使用自动化脚本（推荐）

双击运行 `setup_conda_env.bat`，脚本会自动完成所有配置。

### 方式 2: 手动配置

#### 1. 创建 Conda 环境

```bash
# 使用 environment.yml 创建环境
conda env create -f environment.yml
```

#### 2. 激活环境

```bash
conda activate pyth-311
```

#### 3. 验证安装

```bash
# 检查 Python 版本
python --version  # 应该显示 Python 3.11.x

# 检查关键依赖
python -c "import fastapi; print('FastAPI:', fastapi.__version__)"
python -c "import langchain; print('LangChain:', langchain.__version__)"
python -c "import sqlalchemy; print('SQLAlchemy:', sqlalchemy.__version__)"
python -c "import faiss; print('FAISS: OK')"
```

## 环境管理

### 查看所有 Conda 环境

```bash
conda env list
```

### 更新环境

```bash
conda env update -f environment.yml --prune
```

### 删除环境

```bash
conda deactivate
conda env remove -n pyth-311
```

### 导出当前环境

```bash
conda env export > environment_lock.yml
```

## 配置检查清单

- [ ] Conda 环境创建成功
- [ ] Python 3.11 已安装
- [ ] 所有依赖包安装完成
- [ ] `.env` 文件已配置
- [ ] MySQL 数据库运行中
- [ ] OpenAI API Key 已配置

## 环境变量配置

确保 `.env` 文件包含以下配置：

```env
# 应用配置
APP_NAME="LangChain Learning Kit"
DEBUG=False
LOG_LEVEL=INFO

# 数据库配置
DATABASE_URL=mysql+pymysql://root:123456@localhost:3306/langchain_learning

# OpenAI 配置
OPENAI_API_KEY=sk-your-api-key-here

# FAISS 存储路径
FAISS_BASE_PATH=data/faiss

# 服务器配置
HOST=0.0.0.0
PORT=8000
```

## 常见问题

### Q1: conda 命令未找到

**A**: 确保 Anaconda 或 Miniconda 已正确安装，并且已添加到系统 PATH。

重启命令行工具后再试。

### Q2: 环境创建失败

**A**: 检查网络连接，尝试使用国内镜像源：

```bash
# 配置清华源
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes
```

### Q3: pip 安装缓慢

**A**: 使用国内 pip 镜像：

```bash
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package-name>
```

### Q4: FAISS 安装失败

**A**: Windows 系统确保安装 `faiss-cpu`（不是 `faiss-gpu`）：

```bash
pip install faiss-cpu==1.7.4
```

## 下一步操作

环境配置完成后，按照以下步骤初始化项目：

### 1. 初始化数据库

```bash
# 进入 app 目录
cd app

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

### 2. 验证配置

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

### 3. 启动开发服务器（待实现 main.py 后）

```bash
cd src
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

## PyCharm / VS Code 配置

### PyCharm

1. File → Settings → Project → Python Interpreter
2. 点击齿轮图标 → Add
3. 选择 "Conda Environment" → "Existing environment"
4. 选择: `C:\Users\<你的用户名>\anaconda3\envs\pyth-311\python.exe`

### VS Code

1. Ctrl+Shift+P → "Python: Select Interpreter"
2. 选择: `pyth-311 (conda)`
3. 或手动输入路径: `C:\Users\<你的用户名>\anaconda3\envs\pyth-311\python.exe`

## 开发工作流

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

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

# 3. 运行测试
pytest

# 4. 启动开发服务器
uvicorn app.main:app --reload

# 5. 完成后退出环境
conda deactivate
```

## 依赖管理

### 添加新依赖

1. 编辑 `environment.yml`，在 `pip:` 下添加包
2. 更新环境:

```bash
conda env update -f environment.yml --prune
```

### 或使用 pip 直接安装

```bash
conda activate pyth-311
pip install <package-name>

# 更新 environment.yml
conda env export --from-history > environment.yml
```

## 参考资料

- [Conda 官方文档](https://docs.conda.io/)
- [Conda 环境管理](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
- [pip 国内镜像](https://mirrors.tuna.tsinghua.edu.cn/help/pypi/)