API 兼容模型服务有一项不起眼但至关重要的工作：将多种公共请求格式转换为模型预期的确切提示，然后将生成的 token 转换回客户端预期的响应形状。deepseek-recipe 为 DeepSeek V4 和 V4.1 封装了这一翻译层。

它不运行模型。不开启 HTTP 端口，不执行工具，不搜索网络，也不存储对话。在本教程中保持这一边界可见将节省时间：输出是推理后端可消耗的渲染提示，而非模型答案。

安装 Python 绑定

官方包需要 Python 3.10 或更高版本：

python3 -m pip install deepseek-recipe

对于可复现的项目，请在虚拟环境中安装并在首次验证运行后固定版本。该仓库于 2026 年 9 月新发布，其 API 可能仍在演变。记录您的应用程序选择的 Python 包版本和 V4/V4.1 编码。

该包由一系列 Rust crate 支持。Python 用户无需改用 Rust 重写服务；绑定暴露了正常集成所需的转换和编码类型。

渲染最小化的 V4.1 对话

基于官方示例创建一个小脚本：

from deepseek_recipe import (
    ChatCompletionRequest,
    ConversionOptions,
    DeepseekV41Encoding,
)

request = ChatCompletionRequest({
    "model": "deepseek-flash",
    "messages": [
        {"role": "system", "content": "Answer with one short paragraph."},
        {"role": "user", "content": "Explain sparse attention to a Python developer."},
    ],
    "temperature": 0.2,
})

converted = request.convert(ConversionOptions())
encoding = DeepseekV41Encoding()
rendered = encoding.render_conversation(converted.conversation)

print(rendered.prompt)

这里有两个刻意设计的阶段。request.convert(...) 将 Chat Completions 负载映射到库的共享 Conversation 表示。render_conversation(...) 应用 V4.1 提示编码。保持它们分离允许 API 服务在提交到模型特定的 token 布局之前标准化不同的外部协议。

请求中的模型字符串是面向客户端负载的一部分；所选编码对象控制标准化对话的渲染方式。不要推断任何任意模型名称会自动下载或选择权重。您的周围服务必须验证请求的模型并将提示路由到适当的后端。

Try DeepSeek on MidassAI

连接推理前检查

仅在本地开发测试 fixture 中打印提示，切勿在包含用户数据的生产日志中打印。确认系统和用户消息按预期顺序表示。添加 Unicode、空内容和多行示例。如果您的服务支持图像或工具，请为每种情况创建单独的 fixture，而不是假设仅文本案例能证明兼容性。

这也是进行黄金测试的正确时机。存储一小部分非敏感输入负载和批准的结构期望。确切编码输出可能会在包版本之间合法变化，因此决定版本升级是应该更新快照还是直到审查后才失败。

至少测试：

一个系统和一个用户消息；
包含助手回复的多轮对话；
thinking 模式和您公开的每个支持的 reasoning-effort 值；
temperature、top_p 和输出 token 限制在其允许边缘；
带参数的客户端函数工具；
malformed roles、content types 和 unsupported options。

最后一组很重要，因为协议兼容性也是拒绝兼容性。静默丢弃不支持字段的服务比返回精确错误更难调试。

了解库能转换什么

当前范围涵盖 Messages、Chat Completions 和 Responses 风格请求，包括流式和完整响应。共享表示支持文本、图像、thinking 和客户端工具调用。输出解析涵盖 thinking 内容、工具调用、JSON 对象和停止序列。

对于 Responses 请求，支持工具命名空间和 apply_patch 自定义工具。但这并不意味着库会应用补丁。它表示并解析工具调用；宿主应用程序仍然决定工具是否存在、请求权限、运行它并将结果返回给模型。

V4.1 图像预处理可通过图像组件和 OpenCV 获得。图像可以作为 base64 数据或外部 URL 到达。生产服务在将远程内容交给预处理代码之前，应设置大小限制、媒体类型检查、下载超时和网络限制。

显式处理不支持的字段

截至检查的发布版本，logprobs 和 top_logprobs 不受支持。文档内容、音频或视频、通过 file_id 检索文件、通过 n > 1 多次完成或加密 thinking 内容也不受支持。

结构化输出期望需要小心。库可以解析 JSON 对象输出，但不强制 JSON Schema、正则表达式或严格的工具定义。如果您的 API 宣传这些保证，验证必须在其他地方进行。解析的 JSON 对象仍可能违反调用者的 schema。

对话存储也在包之外。previous_response_id 不检索早期上下文。您的 HTTP 服务必须解析存储的对话状态并将结果消息传入转换，或明确拒绝该字段。

服务器工具（如 web_search）不受支持，因为 recipe 层不执行工具。如果客户端发送此类请求，请在记录语义差异之前不要将其转换为客户端函数调用。

将其添加到 API 服务而不模糊职责

清晰的服务管道有四个边界：

认证、速率限制、body-size 限制和公共 API 验证。
deepseek-recipe 标准化和 V4/V4.1 编码。
消耗 token 并生成 token 的推理后端。
Recipe 解析、应用拥有的工具编排和 HTTP 流式传输。

围绕每个边界保持指标。请求转换时间、首个生成 token 时间、工具等待时间和响应序列化时间回答不同的运营问题。将它们合并为一个延迟数字会使回归难以定位。

默认不要通过日志或追踪系统传递渲染的提示。记录安全的元数据，如消息 count、内容类型、编码版本、token count 和转换错误。如果不可避免的采样负载日志记录，使其成为主动选择、脱敏、访问控制和短寿命的。

何时本教程是错误的路径

当您构建或适配推理服务并需要 DeepSeek 特定协议转换时使用 deepseek-recipe。如果您只想调用现有的 DeepSeek 兼容端点，请使用该服务的客户端 SDK 或 HTTP API。向应用程序客户端添加提示编码器会重复服务器行为并使升级更困难。

该包最有价值之处恰恰在于它不是全能服务器。它为基础设施团队提供共享、可测试的转换层，同时将部署、调度、安全和工具留在他们的控制之下。成功的首次集成以验证的提示和不支持字段列表结束，而不是声称整个服务堆栈已完成。

来源检查：deepseek-recipe 官方仓库，访问于 2026 年 9 月 14 日。

使用 Python 转换 DeepSeek V4.1 API 请求