# AI服务配置指南

## 快速开始

### 1. 复制配置文件
```bash
cd server
cp .env.example .env
```

### 2. 选择 AI服务商

目前支持 4 种 AI服务，**任选其一**即可：

#### 方案 A：DeepSeek（推荐，性价比高）
```env
AI_SERVICE_ENABLED=true
AI_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-a685e8a0e97e41e4b3cb70fa6fcc3af1
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
DEEPSEEK_MODEL=deepseek-chat
```

#### 方案 B：通义千问（国内访问快）
```env
AI_SERVICE_ENABLED=true
AI_PROVIDER=qwen
DASHSCOPE_API_KEY=你的 dashscope API Key
QWEN_MODEL=qwen-plus
```

#### 方案 C：OpenAI（国际版）
```env
AI_SERVICE_ENABLED=true
AI_PROVIDER=openai
OPENAI_API_KEY=sk-your-openai-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-3.5-turbo
```

#### 方案 D：Claude（高质量）
```env
AI_SERVICE_ENABLED=true
AI_PROVIDER=claude
CLAUDE_API_KEY=你的 claude API Key
CLAUDE_MODEL=claude-3-haiku-20240307
```

### 3. 安装依赖
```bash
pip install -r requirements.txt
```

### 4. 启动服务
```bash
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 3000
```

## DeepSeek 详细配置

### API Key 获取
1. 访问 https://platform.deepseek.com/
2. 注册/登录账号
3. 进入控制台 → API Keys
4. 创建新的 API Key
5. 复制到 `.env` 文件的 `DEEPSEEK_API_KEY`

### 计费说明
- **价格**: 输入¥0.002/1K tokens，输出¥0.002/1K tokens（截至 2024 年）
- **免费额度**: 新用户注册赠送¥14 元体验金
- **充值**: 最低充值¥10 元起

### 限流说明
- **QPS**: 默认 3 次/秒
- **RPM**: 默认 60 次/分钟
- **TPM**: 默认 200K tokens/分钟

如需提升限额，联系官方客服。

## 测试 AI 功能

### 方法 1：通过小游戏界面
1. 启动后端服务
2. 打开微信开发者工具
3. 进入任意故事的结局页
4. 点击"✨ AI改写结局"
5. 选择标签或输入自定义指令
6. 点击"✨ 开始改写"

### 方法 2：直接调用 API
```bash
curl -X POST http://localhost:3000/api/stories/1/rewrite \
  -H "Content-Type: application/json" \
  -d '{
    "ending_name": "双向奔赴",
    "ending_content": "原结局内容...",
    "prompt": "让主角逆袭成功"
  }'
```

## 常见问题

### Q: AI_SERVICE_ENABLED=false 会怎样？
A: 将使用模拟数据（随机模板），不会调用真实AI API，不产生费用。

### Q: 可以混合使用多个 AI服务吗？
A: 不建议。每次只能选择一个提供商。如需切换，修改 `AI_PROVIDER` 后重启服务。

### Q: 调用失败怎么办？
A: 系统会自动降级到模拟模式，保证用户体验不受影响。

### Q: 如何查看 Token 消耗？
A: API 返回的 `tokens_used` 字段包含本次消耗的 token 数量。可在日志中查看。

## 安全建议

1. **不要提交`.env` 文件到 Git**
   ```bash
   echo ".env" >> .gitignore
   ```

2. **定期轮换 API Key**
   - 每 3 个月更换一次
   - 发现异常立即更换

3. **设置预算告警**
   - 在 AI 平台设置每月消费上限
   - 开启短信/邮件通知

## 性能优化

### 降低延迟
- 选择地理位置近的 API端点
- 使用 CDN 加速（如 Cloudflare）
- 启用连接池复用

### 降低成本
- 调整 `temperature` 参数（0.7-0.9 之间）
- 限制 `max_tokens`（300-500 足够）
- 缓存相似请求的结果

## 监控指标

建议监控以下指标：
- AI 调用成功率
- 平均响应时间
- Token 消耗速率
- 每日调用次数

可通过 Prometheus + Grafana 搭建监控系统。