企业官网建设流程全解析

• 人工智能
• 大模型
• 基础模型
• DeepSeek

本指南围绕 DeepSeek-V4-Flash-0731 仓库中 encoding/README.md 所定义的 prompt 编码格式，结合 encoding_dsv4.py 参考实现与 test_encoding_dsv4.py 测试用例，系统讲解 DeepSeek-V4 系列模型如何编码多轮对话、工具调用（DSML 格式）、扩展思考（reasoning）以及快速指令任务。读完本文，你将掌握encode_messages/parse_message_from_completion_text两个核心函数的完整语义、每个特殊 token 与参数的真实作用，并能直接复制文中代码构建可运行的对话、工具调用与思考模式请求。

一、编码格式总览：一个自包含的参考实现

DeepSeek-V4 的 prompt 编码格式由 encoding/README.md 正式定义，处理四类核心场景：多轮对话（multi-turn conversations）、工具调用（tool calling）、扩展思考（extended thinking / reasoning）与快速指令任务（quick instruction tasks）。仓库提供了一份自包含的参考实现 encoding_dsv4.py，无需依赖任何外部框架即可完成编码与解码，其主要 API 为：

• encode_messages(messages, thinking_mode, context=None, drop_thinking=True, add_default_bos_token=True, reasoning_effort=None)：把 OpenAI 风格的消息列表编码为 DeepSeek-V4 的 prompt 字符串，是编码的主入口；
• parse_message_from_completion_text(text, thinking_mode)：把模型单轮输出解析回结构化 assistant 消息（含reasoning_content、content、tool_calls三个字段）。

在 inference/generate.py 的交互式推理中，二者被直接串联使用：先用encode_messages(messages, thinking_mode="chat")编码用户输入并调用模型，再用parse_message_from_completion_text(completion, thinking_mode="chat")把生成的文本回填为 assistant 消息，从而支撑多轮对话循环。

快速上手示例

from encoding_dsv4 import encode_messages, parse_message_from_completion_text # 编码一段对话 messages = [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is 2+2?"}, ] prompt = encode_messages(messages, thinking_mode="thinking") # => "<｜begin▁of▁sentence｜>You are a helpful assistant.<｜User｜>What is 2+2?<｜Assistant｜><think>" # 解析模型输出为结构化消息 completion = "Simple arithmetic.</think>2 + 2 = 4.<｜end▁of▁sentence｜>" parsed = parse_message_from_completion_text(completion, thinking_mode="thinking") # => {"role": "assistant", "reasoning_content": "Simple arithmetic.", "content": "2 + 2 = 4.", "tool_calls": []}

注意：parse_message_from_completion_text只处理格式良好的模型输出，不尝试修正或恢复模型偶尔产生的畸形文本；生产环境建议在此基础上增加额外的错误处理。这一点从实现中可得到印证——encoding_dsv4.py 的解析逻辑对缺失</think>、缺失 EOS token、工具调用格式错误、内容中残留特殊 token 等情况一律直接assert或raise ValueError。

二、特殊 Token 与消息角色

特殊 Token 一览

编码格式中定义的全部特殊 token（常量定义见 encoding_dsv4.py）：

另外还有一组面向内部分类任务的快速指令 token（定义于DS_TASK_SP_TOKENS，见 encoding_dsv4.py）：<｜action｜>、<｜query｜>、<｜authority｜>、<｜domain｜>、<｜title｜>、<｜read_url｜>，将在第五节详述。

支持的消息角色

编码支持以下角色：system、user、assistant、tool、latest_reminder和developer。

关于developer角色的说明：developer角色仅用于内部搜索 Agent 流水线（从 tests/test_input_3.json 可见其典型形态——在 developer 消息上定义search/open/find等工具），通用聊天与工具调用任务不需要它，官方 API 也不接受带该角色的消息。

角色渲染规则（源码级）

在render_message（encoding_dsv4.py）中，各角色的渲染逻辑为：

• system：直接输出content；若带tools字段则追加\n\n+ 工具 schema 块；若带response_format字段则追加## Response Format:结构化输出模板；
• developer：内容以<｜User｜>开头（即被编码为一段"用户侧"指令），同样可携带 tools 与 response_format；
• user：输出<｜User｜>前缀，然后输出content；若带content_blocks则逐块渲染（text块原样输出，tool_result块包装进<tool_result>...</tool_result>，未知块类型输出[Unsupported ...]占位）；
• latest_reminder：输出<｜latest_reminder｜>+ 内容；
• tool：直接raise NotImplementedError——DeepSeek-V4 没有独立的 tool 角色，工具结果必须通过merge_tool_messages()预处理合并进 user 消息；
• assistant：渲染顺序为{reasoning}{content}{tool_calls}，最后附 EOS token（可通过wo_eos=True省略 EOS）。

三、对话编码：chat 模式与 thinking 模式

基础多轮对话

一个简单的多轮对话被编码为：

<｜begin▁of▁sentence｜>{system_prompt} <｜User｜>{user_message}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜> <｜User｜>{user_message_2}<｜Assistant｜></think>{response_2}<｜end▁of▁sentence｜>

• BOS token 总在对话最开头预置（add_default_bos_token=True且无前置 context 时，见 encoding_dsv4.py）；
• 在chat 模式（thinking_mode="chat"）下，</think>紧跟在<｜Assistant｜>之后，立即关闭思考块，模型直接生成内容，不产生 reasoning。

交错思考模式（Interleaved Thinking Mode）

在thinking 模式（thinking_mode="thinking"）下，模型先输出显式的<think>...</think>推理块，再给出最终回答：

<｜begin▁of▁sentence｜>{system_prompt} <｜User｜>{message}<｜Assistant｜><think>{reasoning}</think>{response}<｜end▁of▁sentence｜>

drop_thinking 参数：历史推理的裁剪策略

drop_thinking参数默认值为True，控制是否保留较早轮次的推理内容（核心逻辑见 encoding_dsv4.py 与_drop_thinking_messages，encoding_dsv4.py）：

• 无工具场景：drop_thinking生效。最后一个 user 消息之前的所有 assistant 轮次的 reasoning 会被剥离（reasoning_content从消息中移除），只有最后一个 assistant 轮次保留<think>...</think>块；
• 有工具场景（system 或 developer 消息上定义了tools）：drop_thinking自动失效，所有轮次都保留推理。原因是工具调用对话需要完整上下文，模型必须跨多次工具调用追踪多步推理。

该行为在 test_case_2 中得到验证：两轮对话中第一轮 assistant 的reasoning_content（"The user said hello"）在编码结果中缺失，而最后一轮的推理块完整保留。

实际编码示例（无工具、thinking 模式）

输入 tests/test_input_2.json（两轮问答，均带reasoning_content），编码结果见 tests/test_output_2.txt：

<｜begin▁of▁sentence｜>You are a helpful assistant.<｜User｜>Hello<｜Assistant｜></think>Hi there! How can I help you?<｜end▁of▁sentence｜><｜User｜>What is the capital of France?<｜Assistant｜><think>The user asks about the capital of France. It is Paris.</think>The capital of France is Paris.<｜end▁of▁sentence｜>

注意第一轮 assistant 的输出是</think>Hi there!...——由于它在最后一个 user 消息之前，思考块被裁剪，只保留了</think>关闭符；最后一轮则完整包含<think>...</think>。

四、工具调用（DSML 格式）

工具定义与 schema 注入

工具以 OpenAI 兼容格式定义在system或developer消息的tools字段中。当存在工具时，编码器会在 system/user prompt 中注入如下 schema 块（模板见 encoding_dsv4.py 的TOOLS_TEMPLATE）：

## Tools You have access to a set of tools to help answer the user's question. You can invoke tools by writing a "「DSML」tool_calls" block like the following: 「DSML」tool_calls 「DSML」invoke name="$TOOL_NAME" 「DSML」parameter name="$PARAMETER_NAME" string="true|false">$PARAMETER_VALUE「DSML」parameter ... 「DSML」invoke 「DSML」invoke name="$TOOL_NAME2" ... 「DSML」invoke 「DSML」tool_calls

（实际输出中的标记字符为｜DSML｜，为避免混淆，此处用「DSML」代替显示。）

模板随后给出两条使用约束：

1. 字符串参数原样指定并设string="true"；数字、布尔、数组、对象等其余类型以 JSON 传递并设string="false"；
2. 若思考模式被启用（由<think>触发），必须先在<think>...</think>中输出完整推理，再进行任何工具调用或最终回复；否则在</think>之后直接输出工具调用或回复。

最后注入### Available Tool Schemas段：每个工具 schema 以 JSON 行（JSON Lines 风格）列出，并以 "You MUST strictly follow the above defined tool name and parameter schemas to invoke tool calls." 收尾。schema 渲染由render_tools()（encoding_dsv4.py）完成，工具列表先经tools_from_openai_format()抽取tool["function"]字段（encoding_dsv4.py）。

一次真实的工具调用

assistant 轮次中的实际工具调用长这样（见 tests/test_output_1.txt）：

<｜Assistant｜><think>The user wants to know the weather in Beijing. I should use the get_weather tool.</think> 「DSML」tool_calls 「DSML」invoke name="get_weather" 「DSML」parameter name="location" string="true">Beijing「DSML」parameter 「DSML」parameter name="unit" string="true">celsius「DSML」parameter 「DSML」invoke 「DSML」tool_calls<｜end▁of▁sentence｜>

（「DSML」代指｜DSML｜。）规则要点：

• string="true"：参数值为原始字符串（如Beijing、celsius）；
• string="false"：参数值为 JSON（number、boolean、array、object），如{"count": 5}会编码为count参数string="false"。

参数编码实现为encode_arguments_to_dsml()（encoding_dsv4.py）：先把argumentsJSON 字符串json.loads为 dict，再逐参数判断isinstance(v, str)来决定string标志；解码方向对应decode_dsml_to_arguments()（encoding_dsv4.py），将(value, is_string_flag)还原为 JSON 参数字符串。OpenAI 格式与内部格式的互转由tool_calls_from_openai_format/tool_calls_to_openai_format（encoding_dsv4.py）完成。

工具结果的合并与排序

工具执行结果以<tool_result>标签包装在 user 消息中：

<｜User｜><tool_result>{result_json}</tool_result><｜Assistant｜><think>...

由于 DeepSeek-V4 没有独立的 tool 角色，merge_tool_messages()（encoding_dsv4.py）负责把 OpenAI 格式中独立的tool角色消息转换为带content_blocks的 user 消息：tool_result块（携带tool_use_id）与随后的text块会合并进同一个 user 消息。当同一 user 消息中存在多个工具结果时，sort_tool_results_by_call_order()（encoding_dsv4.py）按照前一条 assistant 消息中tool_calls的原始顺序对结果重新排序，保证多工具并行调用时结果与调用一一对应。

端到端示例：带工具的思考对话

输入 tests/test_input_1.json 定义了两个工具（get_weather、search）与四轮消息（system → user → assistant 带工具调用 → tool 结果 → assistant 最终回答），编码结果见 tests/test_output_1.txt：

<｜begin▁of▁sentence｜>You are a helpful assistant. ## Tools ... {"name": "get_weather", "description": "Get the weather for a specific location", "parameters": {...}} {"name": "search", "description": "Search the web for information", "parameters": {...}} You MUST strictly follow the above defined tool name and parameter schemas to invoke tool calls. <｜User｜>What's the weather in Beijing?<｜Assistant｜><think>The user wants to know the weather in Beijing. I should use the get_weather tool.</think> 「DSML」tool_calls 「DSML」invoke name="get_weather" 「DSML」parameter name="location" string="true">Beijing「DSML」parameter 「DSML」parameter name="unit" string="true">celsius「DSML」parameter 「DSML」invoke 「DSML」tool_calls<｜end▁of▁sentence｜><｜User｜><tool_result>{"temperature": 22, "condition": "sunny", "humidity": 45}</tool_result><｜Assistant｜><think>Got the weather data. Let me format a nice response.</think>The weather in Beijing is currently sunny with a temperature of 22°C and 45% humidity.<｜end▁of▁sentence｜>

（「DSML」代指｜DSML｜。）由于系统消息定义了 tools，drop_thinking被自动禁用，两轮 assistant 的思考块都被保留。test_case_1 同时验证了解析侧：从第一个 assistant 轮次中正确提取出 1 个get_weather工具调用（参数还原为{"location": "Beijing", "unit": "celsius"}），从最终轮次提取出纯文本回答。

五、reasoning_effort：思考强度控制

在 thinking 模式下，reasoning_effort参数选择三个等级之一，控制模型在回答前的推理投入程度。该等级仅以文本前缀的形式预置在 prompt 最开头（system 消息之前），其余编码在各等级之间完全一致。三种等级的取值与对应前缀（定义于REASONING_EFFORT_PROMPTS，encoding_dsv4.py）：

reasoning_effort在 chat 模式（thinking_mode="chat"）下无效，因为该模式下模型根本不产生推理块。从实现看，只有index == 0 and thinking_mode == "thinking"时前缀才会被写入（encoding_dsv4.py），且None按"low"处理；传入非法等级会直接触发断言。

"high"的完整前缀文本：

Reasoning Effort: Absolute maximum with no shortcuts permitted. You MUST be very thorough in your thinking and comprehensively decompose the problem to resolve the root cause, rigorously stress-testing your logic against all potential paths, edge cases, and adversarial scenarios. Explicitly write out your entire deliberation process, documenting every intermediate step, considered alternative, and rejected hypothesis to ensure absolutely no assumption is left unchecked.

"max"的完整前缀文本：

Reasoning Effort: Beyond maximum — exhaustive, relentless, and uncompromising. You MUST reason with the utmost depth and rigor, leaving absolutely nothing to chance: exhaustively decompose the problem into its most fundamental components, trace every causal chain to its root, and resolve the underlying cause rather than any surface symptom. Do not stop reasoning until you have independently verified the solution from multiple angles and are certain that no assumption remains unchecked and no error remains undiscovered.

六、快速指令特殊 Token（Quick Instruction Tasks）

快速指令 token 用于辅助分类与生成类任务，通过消息的"task"字段追加，以触发模型输出单 token 或短格式结果。全部 token 由VALID_TASKS校验（encoding_dsv4.py），非法 task 名会触发断言。

消息格式中的使用规则（实现于 encoding_dsv4.py）：

• action任务挂在 user 消息上：<｜action｜>token 放置在 assistant 前缀与思考 token 之后，触发路由决策（例如输出 "Search" 或 "Answer"）；
• 其他任务（query、authority、domain、read_url）挂在 user 消息上：任务 token 直接追加在用户内容之后；
• title任务挂在 assistant 消息上：<｜title｜>token 追加在 assistant 的 EOS 之后，下一条 assistant 消息即提供生成的标题。

实际示例：action 路由任务

tests/test_input_4.json 展示了典型场景：system 消息 + latest_reminder + 一轮带长回答的 assistant + 一个带"task": "action"的 user 消息。编码结果见 tests/test_output_4.txt：

<｜begin▁of▁sentence｜>该助手为DeepSeek-V3，由深度求索公司创造。 今天是2025年10月17日，星期五。<｜latest_reminder｜>2024-11-15,上海市,App,中文<｜User｜>热海大滚锅是世界著名温泉吗<｜Assistant｜></think>关于热海大滚锅...<｜end▁of▁sentence｜><｜User｜>世界著名温泉有哪些<｜Assistant｜></think><｜action｜>Search<｜end▁of▁sentence｜>

（为便于阅读已省略长回答正文。）注意 action 任务的编码特征：在thinking_mode="chat"下，<｜Assistant｜>之后先输出</think>（关闭思考块），再追加<｜action｜>，随后模型直接输出单 token 路由结果Search。

七、模型输出解析：从文本到结构化消息

parse_message_from_completion_text(text, thinking_mode)（encoding_dsv4.py）按以下顺序解析单轮模型输出：

1. thinking 模式下先读取<think>...</think>之间的内容作为reasoning_content（缺失</think>直接断言失败）；
2. 继续读取直到 EOS token 或工具调用块起始标记\n\n「DSML」tool_calls，得到summary_content；
3. 若命中工具调用块，则进入parse_tool_calls()（encoding_dsv4.py）解析invoke name与每个parameter name / string标志，还原为 OpenAI 格式的tool_calls列表；工具调用之后不允许再有其他内容；
4. 校验整段文本已消费完毕，且summary_content/reasoning_content中不残留任何特殊 token。

返回结构固定为：{"role": "assistant", "content": ..., "reasoning_content": ..., "tool_calls": [...]}（tool_calls为 OpenAI 格式）。

八、运行测试验证编码行为

仓库自带完整的测试套件 test_encoding_dsv4.py，共 4 个用例，逐一覆盖上述能力：

• case 1：thinking 模式 + 工具调用（多轮、工具结果合并进 user），编码结果与 tests/test_output_1.txt 逐字符比对，并验证工具调用与最终回答的解析；
• case 2：thinking 模式无工具，验证drop_thinking确实剥离早期轮次的 reasoning；
• case 3：交错思考 + 搜索场景（developer 角色带工具 + latest_reminder，中文内容），对照 tests/test_input_3.json 与 tests/test_output_3.txt；
• case 4：chat 模式下的快速指令任务（action 路由），对照 tests/test_input_4.json 与 tests/test_output_4.txt。

在encoding/目录下执行python test_encoding_dsv4.py即可运行全部测试：

cd encoding && python test_encoding_dsv4.py

期望输出All 4 tests passed!。这些测试既是格式行为的可执行规范，也是自定义对话、工具调用与任务 prompt 时最直接的调试参考。

九、小结与使用建议

DeepSeek-V4 的编码格式可以概括为三条主线：

1. 对话与思考：BOS 开头、<｜User｜>/<｜Assistant｜>分隔角色，<think>...</think>承载推理；thinking 模式默认通过drop_thinking裁剪历史推理以节省上下文，工具场景自动保留全部推理；
2. 工具调用：OpenAI 兼容工具定义经## Tools模板注入，调用以｜DSML｜tool_calls块表达，string属性区分字符串参数与 JSON 参数，工具结果以<tool_result>合并进 user 消息并按调用顺序排序；
3. 任务与强度控制：reasoning_effort以 prompt 前缀实现思考强度分级，task字段触发action/query/authority/domain/title/read_url等单 token 输出任务。

实操建议：通用对话与工具调用场景使用system/user/assistant/tool角色即可；developer角色与action等任务 token 属于内部搜索 Agent 流水线专用；parse_message_from_completion_text仅接受格式良好的输出，生产环境需包裹错误处理。更深入的推理调用方式可参考 inference/README.md 与 inference/generate.py，编码与推理联合起来即构成完整的 DeepSeek-V4 应用闭环。

• 人工智能
• 大模型
• 基础模型
• DeepSeek