deepseek-recipe/README.zh.md

deepseek-recipe

English | 中文

deepseek-recipe 包含一套 Rust 库以及对应的 Python bindings：支持将不同格式的 API 请求统一转换为 Conversation 格式，编码成适用于 DeepSeek 模型的 prompt，并支持将模型输出转换为对应格式的响应。 可用于把推理后端接入兼容多种格式的 API 服务；模型推理、工具执行和 HTTP 传输需由外部提供。

快速上手 · 流式响应 · 使用 tokenizer · 贡献指南 · 许可证

支持范围

• 请求/响应格式： Messages、Chat Completions 与 Responses 的请求转换、流式响应和完整响应，支持文本、图片、思考和客户端工具调用。
• Prompt： 支持将 DeepSeek V4 与 V4.1 的对话编码为 prompt 或 token IDs。
• 生成参数： 思考模式、reasoning effort、temperature、top_p 和输出 token 上限。
• 输出解析： 思考、工具调用、JSON object 输出和 stop sequence。
• 图片： 支持以 base64 或外部 URL 传入。提供基于 OpenCV 的 DeepSeek V4.1 图片预处理。
• 工具定义： 支持函数工具；Responses API 还支持工具命名空间和 apply_patch 自定义工具。

尚未支持

• Token 概率（logprobs 和 top_logprobs）。
• 文档内容、音视频输入和通过 file_id 获取文件。
• 服务端工具执行，例如 web_search。
• JSON Schema、正则表达式输出约束，以及工具 strict 设置的强制执行。
• Chat Completions 单次请求生成多个候选回复（n > 1）。
• Responses 中除 apply_patch 外的自定义工具定义。
• Responses 的会话存储，以及通过 previous_response_id 获取上下文。
• Responses 的加密思考内容（encrypted_content）。

使用 deepseek-recipe

将 Chat Completions 请求转换为 DeepSeek V4.1 prompt：

Python

安装

Python 3.10+：

python3 -m pip install deepseek-recipe

示例

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)

Rust

安装

cargo add deepseek-recipe@0.1 deepseek-recipe-encoding@0.1

源码构建与图片依赖见开发指南。

示例

use deepseek_recipe::openai::ChatCompletionRequest;
use deepseek_recipe::request::{ConversionOptions, ProtocolRequest};
use deepseek_recipe_encoding::PromptEncoding;
use deepseek_recipe_encoding::v4::dsv41::DeepseekV41Encoding;
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let request: ChatCompletionRequest = serde_json::from_value(json!({
        "model": "deepseek-flash",
        "messages": [{"role": "user", "content": "Hello"}],
    }))?;
    let converted = request.convert(ConversionOptions::default())?;
    let rendered = DeepseekV41Encoding::new().render_conversation(&converted.conversation);
    println!("{}", rendered.prompt);
    Ok(())
}

Encoding & Decoding Demo

在仓库根目录运行编解码 demo：

cargo run -p encoding-decoding-demo --locked

打开 http://127.0.0.1:7778。

更多示例

Rust 和 Python 均支持将模型输出转换为流式响应，见流式响应示例；将对话编码为 token IDs、以及直接解码后端返回的 token IDs 的示例见使用 tokenizer。

包与示例

包	用途
deepseek-recipe	协议转换与模型输出解析。
deepseek-recipe-core	共享的对话、消息、图片与工具类型。
deepseek-recipe-encoding	DeepSeek V4 与 V4.1 的 prompt 渲染与 token 编码。
deepseek-recipe-image	图片拉取与预处理。
deepseek-recipe-python	Python bindings，以 deepseek_recipe 导入。
encoding-decoding-demo	编码 prompt、查看 special token，并将完整模型输出解码为 Chat Completions、Responses 或 Messages 的 Web 界面。
server-rs	使用 mock 推理的 Axum API 示例。
server-py	支持 mock 推理的 FastAPI 示例。

许可证

项目代码和公开文档采用 MIT License。随仓库分发的 tokenizer 声明见 static/tokenizers/README.md。