journal_organizer/CLAUDE_API_CONFIGURATION.md

Claude API 配置指南

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

概述

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

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

基本配置

最小配置

claude:
  api_key: "${ANTHROPIC_API_KEY}"

系统将自动使用以下默认值：

• api_url: https://api.anthropic.com
• model: claude-3-5-sonnet-20241022
• max_tokens: 4096
• temperature: 0.7

完整配置示例

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 端点

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

代理服务器配置

企业代理服务器

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

带端口的代理服务器

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

内部 API 网关

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

本地开发环境

HTTP 本地端点

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

HTTPS 本地端点

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

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

区域端点（如果可用）

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

模型配置

支持的模型

当前推荐模型

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

所有支持的模型

# 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"

模型选择建议

生产环境

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

开发和测试

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

复杂分析任务

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

自动模型迁移

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

# 旧配置（自动迁移）
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

环境变量配置

基本环境变量

必需的环境变量

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

可选的环境变量

# 自定义 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"

环境变量语法

基本语法

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

带默认值的语法

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}"

带错误消息的语法

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

环境变量管理

使用 .env 文件

# 创建 .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

永久设置环境变量

# 添加到 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 数配置

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

温度参数配置

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

多环境配置

开发环境

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  # 确定性输出用于测试

生产环境

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

测试环境

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

配置验证

验证配置文件

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

验证环境变量

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

测试配置加载

# 测试完整配置加载
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

解决方案：

• 设置必需的环境变量
• 检查环境变量名称拼写
• 使用带默认值的语法

调试技巧

启用详细日志

python -m journal_organizer --log-level DEBUG organize

检查配置值

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. 使用环境变量存储敏感信息

   # ✅ 推荐
   api_key: "${ANTHROPIC_API_KEY}"
   
   # ❌ 不推荐
   api_key: "sk-ant-actual-key-here"
   

2. 设置适当的文件权限

   chmod 600 config.yaml
   

3. 使用 .gitignore 保护配置文件

   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. 备份重要配置

   cp config.yaml config.yaml.backup
   

示例配置

企业环境完整配置

# 企业环境 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"

开发环境完整配置

# 开发环境 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. 检查是否需要迁移

   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. 执行迁移

   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 获取详细的故障排除指南
2. 检查日志文件中的错误信息
3. 验证环境变量和配置文件格式
4. 测试网络连接和 API 访问

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