# 硅基流动（SiliconFlow）配置说明

## 📋 配置概述

已成功在项目中添加硅基流动（SiliconFlow）大模型 API 支持。

## ⚙️ 配置项

### 环境变量

在 `.env` 文件中添加以下配置：

```bash
# 硅基流动 (SiliconFlow) - 可选
SILICONFLOW_API_KEY=your_siliconflow_api_key_here
SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1/chat/completions
SILICONFLOW_MODEL=deepseek-chat
```

### 配置说明

| 配置项 | 说明 | 默认值 | 必填 |
|--------|------|--------|------|
| `SILICONFLOW_API_KEY` | 硅基流动 API Key | 无 | 是（使用硅基流动时） |
| `SILICONFLOW_BASE_URL` | 硅基流动 API 地址 | `https://api.siliconflow.cn/v1/chat/completions` | 否 |
| `SILICONFLOW_MODEL` | 默认使用的模型 | `deepseek-chat` | 否 |

## 🎯 支持的模型

硅基流动支持多种模型，包括但不限于：

- **DeepSeek 系列**:
  - `deepseek-chat` (推荐，默认)
  - `deepseek-coder`
  - `deepseek-v2`

- **Qwen 系列**:
  - `qwen-turbo`
  - `qwen-plus`
  - `qwen-max`

- **其他模型**: 查看硅基流动官方文档获取完整模型列表

## 💻 使用方法

### 1. 配置 API Key

编辑 `.env` 文件，添加您的硅基流动 API Key：

```bash
SILICONFLOW_API_KEY=sk-xxxxxxxxxxxxx
```

### 2. 在接口中使用

#### 方式一：通过 options 指定模型

```json
{
  "tables": [...],
  "project_id": "project_001",
  "options": {
    "model": "deepseek-chat",
    "temperature": 0.3
  }
}
```

#### 方式二：使用默认配置

如果未指定模型，且配置了 `SILICONFLOW_API_KEY`，系统会自动使用配置的默认模型。

### 3. 模型名称格式

支持以下模型名称格式：

- `deepseek-chat` - 直接使用模型名
- `deepseek-coder` - DeepSeek Coder 模型
- `qwen-turbo` - Qwen Turbo 模型
- `qwen-plus` - Qwen Plus 模型
- `qwen-max` - Qwen Max 模型（通过硅基流动）
- `siliconflow:deepseek-chat` - 带前缀格式（会自动提取模型名）

## 🔧 代码实现

### 配置加载

配置已添加到 `app/core/config.py`：

```python
# 硅基流动 (SiliconFlow)
SILICONFLOW_API_KEY: Optional[str] = os.getenv("SILICONFLOW_API_KEY")
SILICONFLOW_BASE_URL: str = os.getenv(
    "SILICONFLOW_BASE_URL", 
    "https://api.siliconflow.cn/v1/chat/completions"
)
SILICONFLOW_MODEL: str = os.getenv("SILICONFLOW_MODEL", "deepseek-chat")
```

### API 调用

已在 `app/utils/llm_client.py` 中实现硅基流动 API 调用方法：

```python
async def _call_siliconflow(
    self,
    prompt: str,
    system_prompt: Optional[str] = None,
    temperature: float = 0.3,
    model: str = "deepseek-chat",
    **kwargs
) -> str:
    """调用硅基流动 API"""
    # 实现细节...
```

## 🚀 使用示例

### 示例 1: 使用 DeepSeek Chat

```bash
curl -X POST "http://localhost:8000/api/v1/inventory/ai-analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": [...],
    "project_id": "project_001",
    "options": {
      "model": "deepseek-chat",
      "temperature": 0.3
    }
  }'
```

### 示例 2: 使用 Qwen 模型（通过硅基流动）

```bash
curl -X POST "http://localhost:8000/api/v1/inventory/ai-analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": [...],
    "project_id": "project_001",
    "options": {
      "model": "qwen-turbo",
      "temperature": 0.3
    }
  }'
```

## 📝 注意事项

1. **API Key 获取**: 
   - 访问 [硅基流动官网](https://siliconflow.cn) 注册账号
   - 在控制台获取 API Key
   - 将 API Key 添加到 `.env` 文件中

2. **模型选择**:
   - `deepseek-chat` 适合通用对话和文本生成
   - `deepseek-coder` 适合代码相关任务
   - `qwen-*` 系列适合中文场景

3. **API 格式**:
   - 硅基流动使用 OpenAI 兼容的 API 格式
   - 请求和响应格式与 OpenAI 一致

4. **费用**:
   - 请查看硅基流动官方定价
   - 不同模型价格不同
   - 建议先测试少量请求

5. **限流**:
   - 注意 API 调用频率限制
   - 已实现自动重试机制（指数退避）
   - 默认最多重试 3 次

## 🔄 模型优先级

当指定模型名称时，系统按以下优先级选择 API 平台：

1. **通义千问（DashScope）**: 模型名以 `qwen` 开头（不包括通过硅基流动的 qwen）
2. **OpenAI**: 模型名以 `gpt` 或 `openai` 开头
3. **硅基流动**: 
   - 模型名以 `deepseek` 开头
   - 模型名包含 `siliconflow`
   - 模型名为 `qwen-turbo`, `qwen-plus`, `qwen-max`（通过硅基流动）
   - 其他未识别的模型（如果配置了 `SILICONFLOW_API_KEY`）

## ✅ 验证配置

测试配置是否正确：

```bash
# 检查配置加载
source venv/bin/activate
python3 -c "from app.core.config import settings; print(f'SILICONFLOW_API_KEY: {settings.SILICONFLOW_API_KEY is not None}')"
```

## 📚 参考文档

- [硅基流动官方文档](https://siliconflow.cn/docs)
- [API 参考](https://siliconflow.cn/api-reference)
- [模型列表](https://siliconflow.cn/models)

---

**配置完成时间**: 2026-01-10
**支持状态**: ✅ 已实现并可用