langchain-learning-kit/CONFIG_GUIDE.md

# 配置指南

## ✅ 已完成的配置更新

### 1️⃣ Conda 环境名称
- **更新为**: `pyth-311`
- **原名称**: ~~langchain-learning-kit~~

### 2️⃣ OpenAI Base URL 支持
- **新增配置项**: `OPENAI_BASE_URL`
- **用途**: 支持使用代理或转发服务
- **你的配置**: `https://api.openai-proxy.org/v1`

---

## 📝 完整的 .env 配置

请确保你的 `.env` 文件包含以下内容：

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

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

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

# OpenAI 配置
OPENAI_API_KEY=sk-your-actual-api-key-here
OPENAI_BASE_URL=https://api.openai-proxy.org/v1

# FAISS 存储路径
FAISS_BASE_PATH=data/faiss

# 文本分块配置
CHUNK_SIZE=1000
CHUNK_OVERLAP=200
```

---

## 🔧 OpenAI Base URL 使用说明

### 工作原理

1. **配置优先级**:
   - 如果模型配置中指定了 `base_url`，使用模型配置
   - 否则，使用 `.env` 中的 `OPENAI_BASE_URL`
   - 如果都未配置，使用 OpenAI 默认地址

2. **自动应用**:
   - 所有 LLM 调用 (ChatOpenAI)
   - 所有 Embedding 调用 (OpenAIEmbeddings)

### 使用场景

**场景 1: 使用代理服务** (你的情况)
```env
OPENAI_BASE_URL=https://api.openai-proxy.org/v1
```

**场景 2: 使用自定义端点**
```env
OPENAI_BASE_URL=https://your-custom-endpoint.com/v1
```

**场景 3: 不使用代理** (默认)
```env
# OPENAI_BASE_URL 留空或不配置
```

### 验证配置

创建模型后，日志会显示使用的 base_url：

```python
# 日志输出示例
{
  "event": "getting_llm",
  "model_name": "gpt-3.5-turbo",
  "base_url": "https://api.openai-proxy.org/v1"
}
```

---

## 🚀 下一步操作

### 1. 激活环境

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

### 2. 验证配置

```bash
python verify_env.py
```

应该看到：
```
✓ .env 文件存在
✓ DATABASE_URL: mysql+pymysql://root:123...
✓ OPENAI_API_KEY: sk-your-ac...
✓ OPENAI_BASE_URL: https://api.openai...
```

### 3. 初始化数据库

```bash
cd app
alembic upgrade head
```

### 4. 测试配置加载

```bash
python -c "from app.config import get_settings; s = get_settings(); print(f'Base URL: {s.openai_base_url}')"
```

应该输出：
```
Base URL: https://api.openai-proxy.org/v1
```

---

## 📋 环境变量说明

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `APP_NAME` | 否 | "LangChain Learning Kit" | 应用名称 |
| `DEBUG` | 否 | False | 调试模式 |
| `LOG_LEVEL` | 否 | INFO | 日志级别 |
| `HOST` | 否 | 0.0.0.0 | 服务器地址 |
| `PORT` | 否 | 8000 | 服务器端口 |
| `DATABASE_URL` | **是** | - | MySQL 连接字符串 |
| `OPENAI_API_KEY` | **是** | - | OpenAI API Key |
| `OPENAI_BASE_URL` | 否 | None | OpenAI API 基础地址 |
| `FAISS_BASE_PATH` | 否 | data/faiss | FAISS 索引存储路径 |
| `CHUNK_SIZE` | 否 | 1000 | 文本分块大小 |
| `CHUNK_OVERLAP` | 否 | 200 | 文本分块重叠 |

---

## ⚠️ 常见问题

### Q1: 配置了 OPENAI_BASE_URL 但没有生效

**排查步骤**:
1. 确认 `.env` 文件在项目根目录
2. 重启应用 (配置在启动时加载)
3. 检查日志输出确认 base_url

### Q2: 代理地址无法访问

**解决方案**:
1. 检查网络连接
2. 确认代理地址正确
3. 尝试浏览器访问 `https://api.openai-proxy.org/v1/models`

### Q3: 想对不同模型使用不同的 base_url

**解决方案**: 在创建模型配置时指定

```json
{
  "name": "gpt-4-proxy",
  "type": "llm",
  "config": {
    "model_name": "gpt-4",
    "api_key": "${OPENAI_API_KEY}",
    "base_url": "https://custom-proxy.com/v1"
  }
}
```

---

## 💡 提示

1. **环境变量优先级**: 模型配置 > .env 文件 > 默认值
2. **安全性**: 不要将 `.env` 文件提交到 Git (已在 .gitignore)
3. **变量替换**: 配置中可使用 `${VAR_NAME}` 引用环境变量
4. **验证配置**: 使用 `verify_env.py` 脚本检查所有配置

---

**配置更新完成！** ✅

所有文件已更新以支持：
- Conda 环境名称: `pyth-311`
- OpenAI Base URL: `https://api.openai-proxy.org/v1`