journal_organizer/CLAUDE_API_CONFIGURATION.md

# Claude API 配置指南

本指南详细介绍如何配置和使用 Claude API 的增强功能，包括自定义 API 端点、模型选择和环境变量管理。

## 概述

Claude API 配置系统支持以下增强功能：

- **自定义 API 端点**：支持代理服务器、区域端点和自定义部署
- **灵活的模型选择**：支持所有当前 Claude 模型和自动迁移
- **环境变量集成**：完整的环境变量支持和默认值处理
- **向后兼容性**：自动迁移旧配置格式
- **全面的错误处理**：详细的错误消息和修复建议

## 基本配置

### 最小配置

```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"
```

系统将自动使用以下默认值：
- `api_url`: `https://api.anthropic.com`
- `model`: `claude-3-5-sonnet-20241022`
- `max_tokens`: `4096`
- `temperature`: `0.7`

### 完整配置示例

```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"
  api_url: "https://api.anthropic.com"
  model: "claude-3-5-sonnet-20241022"
  max_tokens: 4096
  temperature: 0.7
```

## API 端点配置

### 官方 API 端点

```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"
  api_url: "https://api.anthropic.com"  # 默认官方端点
```

### 代理服务器配置

#### 企业代理服务器

```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"
  api_url: "https://claude-proxy.company.com"
```

#### 带端口的代理服务器

```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"
  api_url: "https://proxy.example.com:8080"
```

#### 内部 API 网关

```yaml
claude:
  api_key: "${COMPANY_CLAUDE_KEY}"
  api_url: "https://api-gateway.internal:8443/claude"
```

### 本地开发环境

#### HTTP 本地端点

```yaml
claude:
  api_key: "local-dev-key"
  api_url: "http://localhost:3128"
```

#### HTTPS 本地端点

```yaml
claude:
  api_key: "local-dev-key"
  api_url: "https://localhost:8080"
```

**注意**：本地 HTTPS 端点会自动禁用 SSL 证书验证。

### 区域端点（如果可用）

```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"
  api_url: "https://api-eu.anthropic.com"  # 欧洲端点
```

## 模型配置

### 支持的模型

#### 当前推荐模型

```yaml
claude:
  model: "claude-3-5-sonnet-20241022"  # 最新最强，推荐用于生产
```

#### 所有支持的模型

```yaml
# Claude 3.5 系列（最新）
model: "claude-3-5-sonnet-20241022"  # 最强性能
model: "claude-3-5-haiku-20241022"   # 快速响应

# Claude 3 系列
model: "claude-3-opus-20240229"      # 最强推理能力
model: "claude-3-sonnet-20240229"    # 平衡性能和成本
model: "claude-3-haiku-20240307"     # 最快最经济

# 最新别名（自动使用最新版本）
model: "claude-3-5-sonnet-latest"
model: "claude-3-5-haiku-latest"
model: "claude-3-opus-latest"
model: "claude-3-sonnet-latest"
model: "claude-3-haiku-latest"
```

### 模型选择建议

#### 生产环境

```yaml
claude:
  model: "claude-3-5-sonnet-20241022"  # 最佳性能
  max_tokens: 4096
  temperature: 0.7
```

#### 开发和测试

```yaml
claude:
  model: "claude-3-haiku-20240307"  # 快速且经济
  max_tokens: 2048
  temperature: 0.5
```

#### 复杂分析任务

```yaml
claude:
  model: "claude-3-opus-20240229"  # 最强推理能力
  max_tokens: 8192
  temperature: 0.3
```

### 自动模型迁移

系统会自动迁移旧的模型名称：

```yaml
# 旧配置（自动迁移）
model: "claude-3-sonnet"     # → claude-3-sonnet-20240229
model: "claude-3-opus"       # → claude-3-opus-20240229
model: "claude-3-haiku"      # → claude-3-haiku-20240307
model: "sonnet"              # → claude-3-5-sonnet-20241022
model: "opus"                # → claude-3-opus-20240229
model: "haiku"               # → claude-3-haiku-20240307
```

## 环境变量配置

### 基本环境变量

#### 必需的环境变量

```bash
# Claude API 密钥（必需）
export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"
```

#### 可选的环境变量

```bash
# 自定义 API 端点
export CLAUDE_API_URL="https://api.anthropic.com"

# 自定义模型
export CLAUDE_MODEL="claude-3-5-sonnet-20241022"

# 自定义参数
export CLAUDE_MAX_TOKENS="4096"
export CLAUDE_TEMPERATURE="0.7"
```

### 环境变量语法

#### 基本语法

```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"          # 必需变量
  api_url: "${CLAUDE_API_URL}"             # 可选变量
```

#### 带默认值的语法

```yaml
claude:
  api_url: "${CLAUDE_API_URL:-https://api.anthropic.com}"
  model: "${CLAUDE_MODEL:-claude-3-5-sonnet-20241022}"
  max_tokens: "${CLAUDE_MAX_TOKENS:-4096}"
  temperature: "${CLAUDE_TEMPERATURE:-0.7}"
```

#### 带错误消息的语法

```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY:?请设置 ANTHROPIC_API_KEY 环境变量}"
```

### 环境变量管理

#### 使用 .env 文件

```bash
# 创建 .env 文件
cat > .env << EOF
ANTHROPIC_API_KEY=sk-ant-your-api-key-here
CLAUDE_API_URL=https://api.anthropic.com
CLAUDE_MODEL=claude-3-5-sonnet-20241022
CLAUDE_MAX_TOKENS=4096
CLAUDE_TEMPERATURE=0.7
EOF

# 加载环境变量
set -a; source .env; set +a
```

#### 永久设置环境变量

```bash
# 添加到 shell 配置文件
echo 'export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"' >> ~/.bashrc
echo 'export CLAUDE_API_URL="https://api.anthropic.com"' >> ~/.bashrc

# 重新加载配置
source ~/.bashrc
```

## 高级配置

### 参数调优

#### 最大 Token 数配置

```yaml
claude:
  max_tokens: 1024    # 短回复，快速响应
  max_tokens: 4096    # 标准回复（推荐）
  max_tokens: 8192    # 长回复，详细分析
  max_tokens: 16384   # 超长回复，复杂任务
```

#### 温度参数配置

```yaml
claude:
  temperature: 0.0    # 最确定的输出
  temperature: 0.3    # 较确定，适合分析任务
  temperature: 0.7    # 平衡创造性和一致性（推荐）
  temperature: 1.0    # 最有创造性的输出
```

### 多环境配置

#### 开发环境

```yaml
claude:
  api_key: "${DEV_CLAUDE_KEY}"
  api_url: "${DEV_CLAUDE_URL:-https://dev-api.example.com}"
  model: "claude-3-haiku-20240307"  # 快速且经济
  max_tokens: 2048
  temperature: 0.0  # 确定性输出用于测试
```

#### 生产环境

```yaml
claude:
  api_key: "${PROD_CLAUDE_KEY}"
  api_url: "https://api.anthropic.com"
  model: "claude-3-5-sonnet-20241022"  # 最佳性能
  max_tokens: 4096
  temperature: 0.7
```

#### 测试环境

```yaml
claude:
  api_key: "${TEST_CLAUDE_KEY}"
  api_url: "${TEST_CLAUDE_URL:-https://test-api.example.com}"
  model: "claude-3-haiku-20240307"
  max_tokens: 1024
  temperature: 0.0
```

## 配置验证

### 验证配置文件

```bash
# 检查配置文件语法
python -c "
import yaml
with open('config.yaml', 'r') as f:
    config = yaml.safe_load(f)
    print('配置文件语法正确')
"
```

### 验证环境变量

```bash
# 检查必需的环境变量
echo "ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-(未设置)}"
echo "CLAUDE_API_URL: ${CLAUDE_API_URL:-(使用默认值)}"
echo "CLAUDE_MODEL: ${CLAUDE_MODEL:-(使用默认值)}"
```

### 测试配置加载

```python
# 测试完整配置加载
from config import Config

try:
    config = Config('config.yaml')
    print('✅ 配置加载成功')
    print(f'API URL: {config.claude.api_url}')
    print(f'Model: {config.claude.model}')
    print(f'Max Tokens: {config.claude.max_tokens}')
    print(f'Temperature: {config.claude.temperature}')
except Exception as e:
    print(f'❌ 配置错误: {e}')
```

## 故障排除

### 常见错误和解决方案

#### API 密钥格式错误

```
ClaudeAPIKeyError: Claude API key should start with 'sk-ant-'
```

**解决方案**：
- 确保 API 密钥以 `sk-ant-` 开头
- 检查密钥长度（应该超过 50 个字符）
- 从 https://console.anthropic.com/ 获取正确的密钥

#### API URL 格式错误

```
ClaudeAPIURLError: Invalid URL format: not-a-url
```

**解决方案**：
- 使用完整的 URL，包括协议（http:// 或 https://）
- 检查 URL 格式是否正确
- 确保端点可访问

#### 模型名称无效

```
ClaudeModelValidationError: Invalid model name: invalid-model
```

**解决方案**：
- 使用支持的模型名称
- 检查模型名称拼写
- 参考本文档的模型列表

#### 环境变量未设置

```
EnvironmentVariableError: Environment variable 'ANTHROPIC_API_KEY' is not set
```

**解决方案**：
- 设置必需的环境变量
- 检查环境变量名称拼写
- 使用带默认值的语法

### 调试技巧

#### 启用详细日志

```bash
python -m journal_organizer --log-level DEBUG organize
```

#### 检查配置值

```python
from config import Config
config = Config('config.yaml')
print(f'实际配置值:')
print(f'  API Key: {"已设置" if config.claude.api_key else "未设置"}')
print(f'  API URL: {config.claude.api_url}')
print(f'  Model: {config.claude.model}')
```

## 最佳实践

### 安全最佳实践

1. **使用环境变量存储敏感信息**
   ```yaml
   # ✅ 推荐
   api_key: "${ANTHROPIC_API_KEY}"
   
   # ❌ 不推荐
   api_key: "sk-ant-actual-key-here"
   ```

2. **设置适当的文件权限**
   ```bash
   chmod 600 config.yaml
   ```

3. **使用 .gitignore 保护配置文件**
   ```bash
   echo "config.yaml" >> .gitignore
   echo ".env" >> .gitignore
   ```

### 性能最佳实践

1. **选择合适的模型**
   - 生产环境：`claude-3-5-sonnet-20241022`
   - 开发测试：`claude-3-haiku-20240307`
   - 复杂任务：`claude-3-opus-20240229`

2. **优化参数设置**
   - 根据任务调整 `max_tokens`
   - 根据需求设置 `temperature`

3. **使用连接池和重试机制**
   - 系统自动处理连接管理
   - 内置错误重试机制

### 维护最佳实践

1. **定期更新配置**
   - 检查新的模型版本
   - 更新 API 端点配置

2. **监控配置变化**
   - 记录配置迁移
   - 验证配置更新

3. **备份重要配置**
   ```bash
   cp config.yaml config.yaml.backup
   ```

## 示例配置

### 企业环境完整配置

```yaml
# 企业环境 Claude API 配置
claude:
  # 使用企业 API 密钥
  api_key: "${COMPANY_CLAUDE_KEY:?请设置企业 Claude API 密钥}"
  
  # 使用企业代理服务器
  api_url: "${CLAUDE_PROXY_URL:-https://claude-proxy.company.com}"
  
  # 使用最新最强模型
  model: "${CLAUDE_MODEL:-claude-3-5-sonnet-20241022}"
  
  # 企业级参数设置
  max_tokens: "${CLAUDE_MAX_TOKENS:-8192}"
  temperature: "${CLAUDE_TEMPERATURE:-0.5}"

# 企业环境变量设置
# export COMPANY_CLAUDE_KEY="sk-ant-company-key-here"
# export CLAUDE_PROXY_URL="https://claude-proxy.company.com"
# export CLAUDE_MODEL="claude-3-5-sonnet-20241022"
# export CLAUDE_MAX_TOKENS="8192"
# export CLAUDE_TEMPERATURE="0.5"
```

### 开发环境完整配置

```yaml
# 开发环境 Claude API 配置
claude:
  # 使用个人 API 密钥
  api_key: "${ANTHROPIC_API_KEY:?请设置 ANTHROPIC_API_KEY 环境变量}"
  
  # 可选择使用本地代理或官方 API
  api_url: "${CLAUDE_API_URL:-https://api.anthropic.com}"
  
  # 开发环境使用快速模型
  model: "${CLAUDE_MODEL:-claude-3-haiku-20240307}"
  
  # 开发环境参数设置
  max_tokens: "${CLAUDE_MAX_TOKENS:-2048}"
  temperature: "${CLAUDE_TEMPERATURE:-0.0}"

# 开发环境变量设置
# export ANTHROPIC_API_KEY="sk-ant-your-personal-key"
# export CLAUDE_API_URL="https://api.anthropic.com"
# export CLAUDE_MODEL="claude-3-haiku-20240307"
# export CLAUDE_MAX_TOKENS="2048"
# export CLAUDE_TEMPERATURE="0.0"
```

## 更新和迁移

### 从旧版本迁移

系统会自动检测和迁移旧配置：

1. **检查是否需要迁移**
   ```python
   from configuration_migrator import ConfigurationMigrator
   migrator = ConfigurationMigrator()
   
   with open('config.yaml', 'r') as f:
       config = yaml.safe_load(f)
   
   if migrator.check_migration_needed(config):
       print('配置需要迁移')
       preview = migrator.get_migration_preview(config)
       for change in preview:
           print(f'  - {change}')
   ```

2. **执行迁移**
   ```python
   migrated_config = migrator.migrate_configuration(config)
   
   with open('config.yaml', 'w') as f:
       yaml.dump(migrated_config, f, default_flow_style=False)
   ```

### 配置更新检查清单

- [ ] API 密钥是否有效
- [ ] API 端点是否可访问
- [ ] 模型名称是否支持
- [ ] 环境变量是否正确设置
- [ ] 配置文件权限是否安全
- [ ] 备份是否已创建

## 支持和帮助

如果遇到配置问题：

1. 查看 [TROUBLESHOOTING.md](TROUBLESHOOTING.md) 获取详细的故障排除指南
2. 检查日志文件中的错误信息
3. 验证环境变量和配置文件格式
4. 测试网络连接和 API 访问

更多信息请参考项目文档和示例配置文件。