ClaudeDesk - Anthropic Claude 实现指南

⚠️ 重要说明

使用限制与建议：

• 国内网络限制：由于 Claude API 在中国大陆地区无法直接访问，本封装未经过充分测试
• 代理服务问题：Claude 的补全接口（Completion API）缺乏稳定可靠的代理服务
• 稳定性风险：该实现的稳定性无法保证，可能存在未知问题
• 推荐替代方案：如需使用 DeskLLM 模式（纯文本生成），强烈建议使用 DeepSeek 作为替代：
• DeepSeek 在多项基准测试中接近 Claude Opus 4.5 水平
• 价格仅为 Claude 的 1/200
• 国内网络访问稳定，经过充分测试

💡 建议： - 如果需要使用 Claude 的多模态能力，请使用 Claude（ChatLLM 实现）而非 ClaudeDesk - 如果只需要纯文本生成，推荐使用 DeepSeekDesk 或 TencentDSDesk

概述

ClaudeDesk 是基于 Anthropic Claude API 的 DeskLLM 实现，提供纯文本生成能力。Claude 系列模型以其出色的推理能力和长上下文窗口而著称。

模型支持

推荐模型（2025年最新）

模型名称	上下文窗口	特点	发布时间
旗舰级
claude-opus-4.5-20250224	200K	最强推理能力，SWE-bench 80.9%，旗舰级性能	2025.02
claude-3-5-sonnet-20241022	200K	平衡性能与成本，适合大多数场景	2024.10
claude-4.5-sonnet-202501XX	1M	长上下文支持，适合超长文档处理	2025.01
经典系列
claude-3-5-sonnet-20240620	200K	Sonnet 系列较早版本	2024.06
claude-3-opus-20240229	200K	Opus 系列经典版本	2024.02
claude-3-haiku-20240307	200K	轻量级，快速响应	2024.03

⚠️ 注意：由于国内网络限制，以上模型在中国大陆地区未经充分测试，使用前请确保有稳定的代理服务。

快速开始

基本使用

from tfrobot.brain.chain.llms.generation_llms.desk_llm.claude_desk import ClaudeDesk
from tfrobot.brain.chain.prompt.memo_prompt import MemoPrompt
from tfrobot.schema.message.conversation.message_dto import TextMessage

# 创建 ClaudeDesk 实例
desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    anthropic_api_key="your_api_key"
)

# 配置系统提示
desk_llm.system_prompt = [
    MemoPrompt(template="你是一个专业的代码助手，擅长 Python 开发。")
]

# 调用
result = desk_llm.complete(
    current_input=TextMessage(content="帮我写一个快速排序函数")
)
print(result.generations[0].text)

配置 API 密钥

通过环境变量配置（推荐）：

export ANTHROPIC_API_KEY="your_api_key"

或直接传入：

desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    anthropic_api_key="your_api_key"
)

核心参数

模型参数

参数	类型	默认值	说明
name	str	claude-3-opus-20240229	模型名称
max_tokens	int	4096	最大生成 tokens 数
temperature	float	1.0	采样温度（0-1）
top_p	float	-	核采样参数
top_k	int	-	Top-K 采样参数
stop	str\|list[str]	-	停止词列表
timeout	int	180	请求超时时间（秒）

网络配置

参数	类型	默认值	说明
anthropic_api_key	str	环境变量	Anthropic API 密钥
base_uri	str	https://api.anthropic.com	API 基础 URL
proxy_host	str	-	代理地址
proxy_port	int	-	代理端口
proxy_user	str	-	代理用户名
proxy_pass	str	-	代理密码

使用场景

代码生成

from tfrobot.brain.chain.llms.generation_llms.desk_llm.claude_desk import ClaudeDesk

desk_llm = ClaudeDesk(name="claude-3-5-sonnet-20241022")

desk_llm.system_prompt = [
    MemoPrompt(template="你是一个 Python 专家，编写高质量、有文档的代码。")
]

desk_llm.purpose_prompt = [
    MemoPrompt(template="创建一个 Person 数据类，包含 name 和 age 属性。")
]

desk_llm.prefix_prompt = [
    MemoPrompt(template="```python\nfrom dataclasses import dataclass\n\n")
]

result = desk_llm.complete(current_input=TextMessage(content="开始生成"))
print(result.generations[0].text)

DSL 生成

desk_llm = ClaudeDesk(name="claude-3-5-sonnet-20241022")

# SQL 生成示例
desk_llm.system_prompt = [
    MemoPrompt(template="你是 SQL 专家，根据自然语言生成 PostgreSQL 查询。")
]

desk_llm.instruction_prompt = [
    MemoPrompt(template="""
示例 1：
输入：查询所有年龄大于 18 的用户
输出：SELECT * FROM users WHERE age > 18;

示例 2：
输入：查询每个部门的平均工资
输出：SELECT department, AVG(salary) FROM employees GROUP BY department;
""")
]

desk_llm.purpose_prompt = [
    MemoPrompt(template="输入：查询销售额排名前 10 的产品")
]

desk_llm.prefix_prompt = [
    MemoPrompt(template="输出：")
]

result = desk_llm.complete(current_input=TextMessage(content="生成 SQL"))

长上下文处理

Claude 支持长达 200K tokens 的上下文窗口：

desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    max_tokens=8192  # 可以生成更长的内容
)

# 处理大型文档
large_document = read_large_file("document.txt")

desk_llm.original_desk_screenshot_prompt = [
    MemoPrompt(template=f"原始文档：\n{large_document}")
]

desk_llm.purpose_prompt = [
    MemoPrompt(template="请总结这个文档的主要内容，并列出关键点。")
]

result = desk_llm.complete(current_input=TextMessage(content="开始总结"))

代理配置

HTTP 代理

desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    proxy_host="127.0.0.1",
    proxy_port=7890
)

带认证的代理

desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    proxy_host="proxy.company.com",
    proxy_port=8080,
    proxy_user="username",
    proxy_pass="password"
)

自定义 API 端点

# 使用兼容 Anthropic API 的第三方服务
desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    base_uri="https://custom-api.example.com",
    anthropic_api_key="custom_key"
)

错误处理

上下文超长

ClaudeDesk 会自动检测并处理上下文超长错误：

from tfrobot.schema.exceptions import ContextTooLargeError

try:
    result = desk_llm.complete(current_input=very_long_input)
except ContextTooLargeError as e:
    print(f"当前大小: {e.current_size} tokens")
    print(f"目标大小: {e.target_size} tokens")
    print(f"模型: {e.model_name}")
    # 由 Chain 层自动处理上下文压缩

重试机制

ClaudeDesk 使用 tenacity 实现自动重试：

• 重试条件：APITimeoutError, APIConnectionError
• 重试次数：3 次
• 重试策略：指数退避（1s, 2s, 4s... 最大 10s）

import logging

# 配置日志记录重试
logging.basicConfig(level=logging.WARNING)

高级用法

多轮编辑

from tfrobot.brain.chain.llms.generation_llms.desk_llm.claude_desk import ClaudeDesk

desk_llm = ClaudeDesk(name="claude-3-5-sonnet-20241022")

# 初始代码
original_code = """
def add(a, b):
    return a + b
"""

desk_llm.original_desk_screenshot_prompt = [
    MemoPrompt(template=f"原始代码：\n```python\n{original_code}\n```")
]

# 第一轮：添加类型注解
desk_llm.purpose_prompt = [
    MemoPrompt(template="添加类型注解。")
]

result1 = desk_llm.complete(current_input=TextMessage(content="开始编辑"))
current_code = result1.generations[0].text

# 第二轮：添加文档字符串
desk_llm.current_desk_screenshot_prompt = [
    MemoPrompt(template=f"当前代码：\n```python\n{current_code}\n```")
]

desk_llm.intermediate_prompt = [
    MemoPrompt(template="已添加类型注解。")
]

desk_llm.purpose_prompt = [
    MemoPrompt(template="添加文档字符串。")
]

result2 = desk_llm.complete(current_input=TextMessage(content="继续编辑"))
print(result2.generations[0].text)

使用停止词

# 在生成 JSON 时使用停止词
desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    stop=["```", "END"]  # 在遇到这些词时停止生成
)

desk_llm.purpose_prompt = [
    MemoPrompt(template="生成一个 JSON 对象，包含 name 和 age 字段。")
]

result = desk_llm.complete(current_input=TextMessage(content="开始"))

最佳实践

1. 选择合适的模型

# 💡 强烈建议：对于大多数场景，优先考虑使用 DeepSeekDesk
# from tfrobot.brain.chain.llms.generation_llms.desk_llm.deepseek_desk import DeepSeekDesk
# desk_llm = DeepSeekDesk(name="deepseek-chat")  # 性能接近 Claude，价格仅为 1/200

# 如果必须使用 Claude（建议仅在海外环境下）：

# 简单任务使用 Haiku（快速、经济）
desk_llm = ClaudeDesk(name="claude-3-haiku-20240307")

# 大多数任务使用 Sonnet（平衡）
desk_llm = ClaudeDesk(name="claude-3-5-sonnet-20241022")

# 复杂推理使用最新 Opus 4.5（最强，旗舰级）
desk_llm = ClaudeDesk(name="claude-opus-4.5-20250224")

# 超长文档使用 Claude 4.5 Sonnet（1M 上下文）
desk_llm = ClaudeDesk(name="claude-4.5-sonnet-202501XX")

2. 合理设置 max_tokens

# 对于简单任务，限制输出长度
desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    max_tokens=1024  # 减少延迟和成本
)

3. 使用温度控制输出多样性

# 确定性输出（代码生成）
desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    temperature=0.0
)

# 创造性输出（文案创作）
desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    temperature=0.8
)

4. 利用长上下文窗口

# Claude 支持长达 200K tokens 的上下文
desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    max_tokens=8192
)

# 可以处理整个代码库或长文档
codebase = load_entire_codebase()
desk_llm.original_desk_screenshot_prompt = [
    MemoPrompt(template=f"代码库内容：\n{codebase}")
]

性能优化

1. 减少 Prompt 长度

# 避免冗长的 Prompt
desk_llm.system_prompt = [
    MemoPrompt(template="你是 Python 专家。")  # 简洁明了
]

2. 使用合适的采样参数

# 对于代码生成，使用低温度和高 Top-K
desk_llm = ClaudeDesk(
    name="claude-3-5-sonnet-20241022",
    temperature=0.0,
    top_k=40
)

3. 异步调用

import asyncio

async def generate():
    desk_llm = ClaudeDesk(name="claude-3-5-sonnet-20241022")
    result = await desk_llm.async_complete(
        current_input=TextMessage(content="生成代码")
    )
    return result.generations[0].text

result = asyncio.run(generate())

相关文档

替代方案（推荐）

由于 ClaudeDesk 在国内网络环境下的限制，建议考虑以下替代方案：

• DeepSeekDesk 使用指南 - 性能接近 Claude，价格仅为 1/200，国内访问稳定
• TencentDSDesk 使用指南 - 腾讯云 DeepSeek 接入，国内企业级稳定性
• OpenAIDesk 使用指南 - OpenAI GPT 系列模型的 DeskLLM 实现

技术文档

• DeskLLM 技术文档
• Anthropic API 官方文档
• Claude 模型列表

其他 Claude 实现

• Claude (ChatLLM) - 支持多模态和工具调用的 Claude 实现（推荐使用）