DeepSeek Recipe：DeepSeek 官方多协议 Prompt 编码库

DeepSeek 官方出品，将 OpenAI Messages / Chat Completions / Responses 等多种 API 格式统一转换为 DeepSeek V4/V4.1 模型 Prompt，并完成输出解析。Rust 实现，Python 一行安装，MIT 协议开源。

背景：从"格式孤岛"到"协议统一"

如果你同时在用 OpenAI SDK、Anthropic SDK 和各种第三方推理服务，大概率遇到过这样的痛苦：每换一种后端就要改一次请求格式——role 字段写法不同、tool_call 结构不同、流式响应 SSE 字段不同。每接入一个模型，就是一次新的适配工程。

DeepSeek 解决这个问题的方式很彻底：他们自己维护了一个官方库 deepseek-recipe，把"发送什么格式的请求"和"模型需要什么 Prompt"彻底解耦。无论你是用 OpenAI 的 Messages 格式、Anthropic 的 Responses 格式，还是 DeepSeek 原生的格式，传入后都会被统一转换为模型能理解的结构。

这个库由 DeepSeek 官方维护，2026 年 9 月发布 0.1.0 版本，当前已有 370+ GitHub Stars，是 DeepSeek 生态中连接上游推理框架和下游 API 服务的关键中间件。

核心能力：三层协议转换

deepseek-recipe 的架构分为三个层次，理解了这三个层次，就理解了整个库的定位。

第一层：请求格式转换（Protocol → Conversation）

deepseek-recipe-core 负责把不同来源的 API 请求统一转换为内部的 Conversation 格式。支持三种主流协议：

• Chat Completions（OpenAI 兼容）：最广泛使用的对话格式，role + content 结构
• Responses（Anthropic 兼容）：更结构化的响应格式，支持多轮上下文继承
• Messages（DeepSeek 原生）：DeepSeek 平台原生协议

无论你用哪种格式发起请求，ChatCompletionRequest / ResponsesRequest / MessagesRequest 都会将其中携带的消息内容、工具定义、图片数据统一提取，存入内部 Conversation 结构。

第二层：Prompt 编码（Conversation → Prompt）

deepseek-recipe-encoding 负责把 Conversation 编码为 DeepSeek 模型实际消耗的 Token 序列。支持：

• DeepSeek V4：标准对话 Prompt 模板
• DeepSeek V4.1：带图片理解的增强 Prompt 模板，支持多模态输入

编码过程会处理特殊 Token（思考 Token、工具 Token、边界 Token）、对话角色标记（eos_id、bos_id 等），最终输出一个可直接送入模型的 Token 序列或字符串 Prompt。

第三层：输出解析（Model Output → 协议响应）

模型输出是纯 Token 流，StreamProcessor 负责将流式 Token 实时解析为：

• 思考内容（thinking）
• 工具调用指令（tool_calls）
• 最终回复文本（content）
• JSON 结构化输出（object）

解析过程支持 SSE（Server-Sent Events）流式推送，每解析出一个语义单元就立即返回，延迟极低。

技术细节：Rust + 混成管理

语言构成： Rust 86.1%、Python 9%（Bindings）、JavaScript 2.6%

项目采用 Rust workspace 管理，包含 5 个核心 crate：

包	职责
deepseek-recipe-core	数据类型定义：Conversation、Message、Image、Tool
deepseek-recipe-encoding	Prompt 模板编码、Token 序列生成
deepseek-recipe-image	图片获取与预处理（支持 base64 / URL / OpenCV）
deepseek-recipe-python	Python bindings，通过 PyO3 暴露 Rust API
encoding-decoding-demo	浏览器 Demo，实时演示编码/解码过程

图片处理（V4.1 特性）：

deepseek-recipe-image 支持以 base64 字符串或外部 URL 两种方式传入图片，内部通过 OpenCV 进行 V4.1 要求的预处理（缩放、归一化、格式转换）。如果不想引入 OpenCV 依赖，也可以实现自定义的 ImagePreprocessor 接口。

Python 使用（1 行安装）：

from deepseek_recipe import ChatCompletionRequest, ConversionOptions, DeepseekV41Encoding

request = ChatCompletionRequest({{
    "model": "deepseek-flash",
    "messages": [{{"role": "user", "content": "Hello"}}],
}})
converted = request.convert(ConversionOptions())
rendered = DeepseekV41Encoding().render_conversation(converted.conversation)
print(rendered.prompt)  # 输出 V4.1 可用的完整 Prompt

Rust 使用（cargo add 2 行）：

use deepseek_recipe::openai::ChatCompletionRequest;
use deepseek_recipe_encoding::v4::dsv41::DeepseekV41Encoding;

let request: ChatCompletionRequest = serde_json::from_value(json!({{
    "model": "deepseek-flash",
    "messages": [{{"role": "user", "content": "Hello"}}],
}}))?;
let rendered = DeepseekV41Encoding::new()
    .render_conversation(&converted.conversation);
println!("{{}}", rendered.prompt);

配套服务：API 服务端示例

除了核心库，项目还提供了两个可直接运行的 API 服务端：

Python 服务（FastAPI）：

pip install deepseek-recipe  # 或本地编译 Python bindings
uvicorn main:app --host 127.0.0.1 --port 7777

支持 /v1/chat/completions、/v1/responses、/v1/messages 三个端点，JSON 和 SSE 流式响应均支持。内置 Mock 推理引擎，零配置即可演示完整流程。

Rust 服务（Axum）： 基于 server-rs crate，提供相同协议支持的 Rust 原生实现。

上手体验：Demo 零门槛

最友好的上手方式是运行内置的编码/解码 Demo：

cargo run -p encoding-decoding-demo --locked
# 打开 http://127.0.0.1:7778

在浏览器页面中输入对话内容，选择目标模型（V4 / V4.1），即可实时看到：原始 Message 结构 → 编码后的 Token 序列 → 解码后的协议响应。整个过程透明可见，是理解 DeepSeek Prompt 格式的最佳工具。

局限与边界

需要明确的是，deepseek-recipe 不包含模型推理本身。它只负责格式转换，推理引擎需要另外接入。官方 Demo 中的 Mock 推理引擎仅用于演示，生产环境需要接入真实的后端（如 vLLM、TGI、或 DeepSeek 自有推理服务）。

此外，以下功能尚不支持：

• logprobs / top_logprobs（Token 概率）
• 服务端工具执行（如 web_search）
• JSON Schema / Regex 输出约束
• 多候选回复（n > 1）
• 音视频输入

行业意义：中间件的"标准先行"

deepseek-recipe 的出现标志着 DeepSeek 在工具链生态上的一次重要补全。在 AI 应用层，能兼容越多协议，就能接入越多现有工具——LangChain、LlamaIndex、OpenAI SDK 的用户无需修改代码，只需换掉底层模型名称，就能用上 DeepSeek。

370 Stars（发布不足一个月）的增长曲线说明市场对此类中间件有明确需求。随着 DeepSeek V4.1 的发布和多模态能力的增强，类似 deepseek-recipe 的协议适配层将成为生态标配。