DeepSeekDesk - DeepSeek 实现指南

概述

DeepSeekDesk 是基于 DeepSeek API 的 DeskLLM 实现，提供纯文本生成能力。DeepSeek 模型以其出色的中文理解和代码生成能力而著称，同时支持 FIM（Fill-in-the-Middle）模式。

模型支持

推荐模型

模型名称	上下文窗口	特点
deepseek-chat	128K	通用对话模型，中文能力强
deepseek-coder	128K	代码专用模型
deepseek-r1	64K	推理模型，支持复杂思维链

快速开始

基本使用

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

# 创建 DeepSeekDesk 实例
desk_llm = DeepSeekDesk(
    name="deepseek-chat",
    deepseek_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 DEEPSEEK_API_KEY="your_api_key"

或直接传入：

desk_llm = DeepSeekDesk(
    name="deepseek-chat",
    deepseek_api_key="your_api_key"
)

核心参数

模型参数

参数	类型	默认值	说明
name	str	deepseek-chat	模型名称
max_tokens	int	-	最大生成 tokens 数
temperature	float	1.0	采样温度（0-2）
top_p	float	1.0	核采样参数
stop	str\|list[str]	-	停止词列表（最多 16 个）
stream	bool	False	是否流式输出
timeout	int	180	请求超时时间（秒）

网络配置

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

特殊功能

FIM（Fill-in-the-Middle）模式

DeepSeekDesk 支持 FIM 模式，类似于完形填空：

from tfrobot.brain.chain.llms.generation_llms.desk_llm.deepseek_desk import DeepSeekDesk

desk_llm = DeepSeekDesk(name="deepseek-coder")

# 前缀（prefix）
desk_llm.prefix_prompt = [
    MemoPrompt(template="def quicksort(arr):\n    ")
]

# 后缀（suffix）- 希望模型达到的状态
desk_llm.suffix_prompt = [
    MemoPrompt(template="\n    return sorted_arr")
]

# 模型会在中间生成代码
result = desk_llm.complete(current_input=TextMessage(content="完成函数"))
print(result.generations[0].text)

使用场景

代码生成

desk_llm = DeepSeekDesk(name="deepseek-coder")

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)

中文内容生成

DeepSeek 在中文场景下表现优异：

desk_llm = DeepSeekDesk(name="deepseek-chat")

desk_llm.system_prompt = [
    MemoPrompt(template="你是一个专业的文案撰写助手。")
]

desk_llm.purpose_prompt = [
    MemoPrompt(template="为一款智能家居产品撰写一段宣传文案，突出便捷性和智能化。")
]

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

代码补全（使用 FIM）

desk_llm = DeepSeekDesk(name="deepseek-coder")

# 前缀：函数定义开始
desk_llm.prefix_prompt = [
    MemoPrompt(template="""
def fibonacci(n):
    \"\"\"计算斐波那契数列的第 n 项。

    Args:
        n: 要计算的项数

    Returns:
        第 n 项的值
    \"\"\"
    if n <= 1:
        return n
    """)
]

# 后缀：函数结束
desk_llm.suffix_prompt = [
    MemoPrompt(template="""
    return result
""")
]

# 模型会补全中间的实现
result = desk_llm.complete(current_input=TextMessage(content="补全函数"))
print(result.generations[0].text)

代理配置

HTTP 代理

desk_llm = DeepSeekDesk(
    name="deepseek-chat",
    proxy_host="127.0.0.1",
    proxy_port=7890
)

带认证的代理

desk_llm = DeepSeekDesk(
    name="deepseek-chat",
    proxy_host="proxy.company.com",
    proxy_port=8080,
    proxy_user="username",
    proxy_pass="password"
)

自定义 API 端点

# 使用兼容 OpenAI API 的第三方服务
desk_llm = DeepSeekDesk(
    name="deepseek-chat",
    base_url="https://custom-api.example.com/v1",
    deepseek_api_key="custom_key"
)

错误处理

上下文超长

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

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 层自动处理上下文压缩

网关断开连接

当请求体过大时，网关可能直接断开连接：

try:
    result = desk_llm.complete(current_input=huge_input)
except ContextTooLargeError as e:
    # DeepSeek 会检测请求体是否超过 10MB
    if "gateway dropped connection" in str(e):
        print("请求体过大，请减少输入大小")

重试机制

DeepSeekDesk 使用 tenacity 实现自动重试：

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

import logging

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

高级用法

多轮编辑

from tfrobot.brain.chain.llms.generation_llms.desk_llm.deepseek_desk import DeepSeekDesk

desk_llm = DeepSeekDesk(name="deepseek-coder")

# 初始代码
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 = DeepSeekDesk(
    name="deepseek-chat",
    stop=["```", "END"]  # 在遇到这些词时停止生成
)

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

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

流式输出

desk_llm = DeepSeekDesk(
    name="deepseek-chat",
    stream=True
)

# 注意：流式输出尚未完全实现，会抛出 NotImplementedError

最佳实践

1. 选择合适的模型

# 代码任务使用 Coder
desk_llm = DeepSeekDesk(name="deepseek-coder")

# 通用对话使用 Chat
desk_llm = DeepSeekDesk(name="deepseek-chat")

# 复杂推理使用 R1
desk_llm = DeepSeekDesk(name="deepseek-r1")

2. 利用 FIM 模式

# FIM 适用于代码补全场景
desk_llm = DeepSeekDesk(name="deepseek-coder")

desk_llm.prefix_prompt = [
    MemoPrompt(template="def function():\n    ")
]

desk_llm.suffix_prompt = [
    MemoPrompt(template="\n    return result")
]

result = desk_llm.complete(current_input=TextMessage(content="补全中间部分"))

3. 合理设置温度

# 确定性输出（代码生成）
desk_llm = DeepSeekDesk(
    name="deepseek-coder",
    temperature=0.0
)

# 创造性输出（文案创作）
desk_llm = DeepSeekDesk(
    name="deepseek-chat",
    temperature=1.2
)

4. 中文场景优化

# DeepSeek 在中文场景下表现优异
desk_llm = DeepSeekDesk(name="deepseek-chat")

desk_llm.system_prompt = [
    MemoPrompt(template="你是一个专业的中文写作助手。")
]

性能优化

1. 减少 Prompt 长度

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

2. 使用合适的采样参数

# 对于代码生成，使用低温度
desk_llm = DeepSeekDesk(
    name="deepseek-coder",
    temperature=0.0,
    top_p=0.95
)

3. 异步调用

import asyncio

async def generate():
    desk_llm = DeepSeekDesk(name="deepseek-chat")
    result = await desk_llm.async_complete(
        current_input=TextMessage(content="生成代码")
    )
    return result.generations[0].text

result = asyncio.run(generate())

Token 计算说明

DeepSeekDesk 使用 DeepSeek V3 的 tokenizer 进行 token 计算：

# 自动使用 DeepSeek tokenizer
desk_llm = DeepSeekDesk(name="deepseek-chat")

result = desk_llm.complete(current_input=user_input)

# Token 使用情况
print(result.usage)
# {
#     "prompt_tokens": 100,
#     "completion_tokens": 50,
#     "total_tokens": 150,
#     "prompt_cost": 0.0001,
#     "completion_cost": 0.0002,
#     "total_cost": 0.0003
# }

与其他实现的区别

特性	DeepSeekDesk	ClaudeDesk	GPTDesk
FIM 支持	✅	❌	❌
中文能力	强	中	中
代码能力	强	强	强
API 兼容性	OpenAI	Anthropic	OpenAI
上下文窗口	128K	200K	128K

相关文档

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