Initial project setup: Obsidian intelligent journal organizer
- Add core agent architecture with Command + Skill pattern - Implement Claude API integration for content analysis - Add Obsidian REST API integration for vault operations - Create conversational interface (v2.0) with natural language processing - Add comprehensive configuration management and validation - Include project documentation and developer guides - Set up testing framework with unit, integration, and property tests - Add Kiro specs for Claude API configuration and code quality improvements - Configure project steering files for development guidelines
This commit is contained in:
windyboy
@@ -0,0 +1,581 @@
|
||||
# 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 访问
|
||||
|
||||
更多信息请参考项目文档和示例配置文件。
|
||||
Reference in New Issue
Block a user