DeepSeek 插件配置说明

一、概述

nbdeepseek 是一款针对 DeepSeek / OpenAI 兼容的流式 Chat Completion API 的网络与生成性能测量插件。它通过发送真实的流式对话请求，测量从网络层（DNS、TCP、SSL、TTFB）到 LLM 生成层（首 Token 延迟、推理速度、内容速度）的全链路指标。

二、输入配置参数详解

2.1 API 连接参数

参数名	别名	类型	是否必填	默认值	说明与影响
`base_url`	`url`	string	是	—	API 基础 URL，例如 `https://api.deepseek.com/v1`。插件会向 `{base_url}/{endpoint}` 发送 POST 请求。若填写不完整，可能导致请求 404 或连接失败。
`endpoint`	—	string	否	`chat/completions`	API 端点路径，拼接在 `base_url` 之后。若目标服务使用非标准端点（如自定义网关），可通过此参数修改。
`api_key`	`key`	string	是	—	Bearer Token，用于 `Authorization: Bearer <api_key>` 请求头。若缺失或无效，API 将返回 401 未授权错误。

2.2 请求内容参数

参数名	类型	是否必填	默认值	说明与影响
`model`	string	否	`""`	请求使用的模型名称，填入 JSON 的 `model` 字段。若为空，部分网关可能报错，部分可能使用默认模型。
`prompt`	string	否	`""`	用户消息内容，填入 JSON 的 `messages[0].content` 字段。直接影响 LLM 的生成内容长度和主题，从而显著影响 Token 数量和生成耗时。建议固定 prompt 以获得可对比的基准数据。

2.3 超时与网络参数

参数名	类型	是否必填	默认值	说明与影响
`timeout`	integer	否	`300000`	整体下载超时，单位毫秒（5 分钟）。从发送请求开始到完整接收流式响应的总时间上限。若 LLM 生成内容较长或网络较慢，需适当增大，否则会被强制中断并上报超时错误。
`readtimeut`	integer	否	`30000`	套接字单次读取超时，单位毫秒。注意拼写为 `readtimeut`（非 `readtimeout`）。若两次 SSE 数据块之间的间隔超过此值，将触发读取超时错误。用于检测流式响应中的长时间卡顿。

2.4 验证与质量控制参数

参数名	类型	是否必填	默认值	说明与影响
`check`	string	否	`""`	响应内容验证规则。用于确保 LLM 返回了预期内容，而非乱码或错误信息。 • 纯文本：执行子串包含匹配（大小写敏感）。 • 正则表达式：使用 `/pattern/` 包裹，如 `/hello.+/`，执行正则匹配。若验证失败，插件将上报 `699002` 错误码。
`cspm`	integer	否	`100`	Content Speed Percentage Multiplier（内容速度百分比乘数）。质量控制阈值，用于检测异常响应。计算逻辑：若 `contentSpeed / reasoningSpeed * 100 - 100 >= cspm`，即内容生成速度比推理速度快超过 `cspm`%，则判定结果异常，上报 `612280`（客户端错误）。该值越大，容忍的速度差异越大；设为 `0` 则任何 contentSpeed > reasoningSpeed 都会报错。

三、输出指标详解

3.1 数值性能指标

stage	指标名	单位	说明
`0`	总耗时	ms	从发起 HTTP 请求到完整接收流式响应的整体耗时。是衡量 API 端到端性能的核心指标。
`1`	DNS 解析时间	ms	解析 `base_url` 域名到 IP 的耗时。若使用 IP 直连，则接近 0。
`2`	TCP 连接时间	ms	建立 TCP 三次握手的耗时。反映网络层到目标服务器的直连质量。
`3`	SSL / TLS 握手时间	ms	HTTPS 加密握手耗时。包含证书交换、密钥协商等。
`4`	请求发送时间	ms	发送 HTTP POST 请求头及 Body 的耗时。通常极小，但若上行带宽受限或 Body 极大（如图片 URL），可能显著增大。
`5`	TTFB（首字节时间）	ms	从发送完请求到收到第一个响应字节的时间。反映服务器处理首包的响应速度，是衡量 API 延迟的关键指标。
`6`	剩余接收时间	ms	从首字节之后到完整接收整个流式响应的时间。主要受 LLM 生成速度和生成长度影响。
`7`	首 Token 延迟	ms	从请求开始到收到第一个带有实际内容（`delta.content` 或 `delta.reasoning_content`）的 SSE 数据块的时间。这是衡量 LLM 响应灵敏度的核心指标。
`8`	推理 Token 速度	tokens / s × 1000	推理内容（`reasoning_content`）的生成速度。数值需除以 1000 得到真实的 tokens / s。反映模型思考过程的吞吐率。
`9`	内容 Token 速度	tokens / s × 1000	正式回复内容（`content`）的生成速度。数值需除以 1000。反映模型正文输出的吞吐率。
`10`	平均整体速度	tokens / s × 1000	总 Token 数（推理 + 内容）除以总耗时的速度。数值需除以 1000。用于横向对比不同模型 / 服务的综合生成效率。
`11`	推理 Token 数量	tokens	累计的 `reasoning_content` Token 数。通过 SSE 流中的内容按空白字符拆分估算。
`12`	内容 Token 数量	tokens	累计的 `content` Token 数。同上，按空白字符拆分估算。
`13`	推理生成时间	ms	从开始输出 reasoning_content 到 reasoning_content 结束的时间窗口。
`14`	内容生成时间	ms	从开始输出 content 到 content 结束的时间窗口。
`15`	Completion 速度	tokens / s × 1000	基于 API 返回的 `usage.completion_tokens` 计算的完成速度（`completion_tokens / 总耗时 × 1000`）。与 stage 10 的区别在于使用官方统计而非流式估算。

3.2 文本与诊断信息

stage	说明
`0`	日志 / 调试信息。常规日志、调试输出、`debug=true` 时的响应内容等。
`1`	服务器 IP。`base_url` 域名解析后的实际 IP 地址。
`2`	目标主机名。`base_url` 中的域名部分。

3.3 错误码

info 值	含义	触发条件
`612280`	客户端错误	配置缺失（无 URL 或 key）、内容速度异常（`cspm` 校验失败）等通用客户端问题。
`699001`	推理错误	流式响应结束后，总 Token 数 `< 1` 或内容 Token 数 `< 1`。通常说明模型返回为空、超时中断或流异常结束。
`699002`	内容检查失败	`check` 参数指定的文本或正则未在最终生成的 `content` 中匹配到。
标准错误	网络 / HTTP 错误	DNS 失败（如 `612007`）、连接失败、SSL 失败、HTTP 4xx/5xx、读取超时等。

四、速度计算与校验逻辑

4.1 Token 计数方式

插件在流式接收过程中，对每个 SSE chunk 的 delta.reasoning_content 和 delta.content 按正则 \s+（空白字符）拆分计数。这与官方 usage 中的 tokenizer 计数可能存在差异，因此：

stage 11/12（推理 / 内容 Token 数）为流式估算值。

stage 15（Completion 速度）基于官方的 usage.completion_tokens，更为准确但可能只在流结束后才收到。

4.2 cspm 校验示例

假设 cspm=100：

reasoningSpeed	contentSpeed	计算	结果
1000 (1.0 t / s)	1500 (1.5 t / s)	`1500/1000*100-100 = 50`	`50 < 100`，通过
1000 (1.0 t / s)	2500 (2.5 t / s)	`2500/1000*100-100 = 150`	`150 >= 100`，失败，报 `12280`

五、典型配置示例

5.1 基础 DeepSeek API 测试

base_url=https://api.deepseek.com/v1
api_key=sk-xxxxxxxxxxxxxxxx
model=deepseek-chat
prompt=请用一句话解释什么是人工智能
timeout=120000
readtimeut=30000

5.2 带内容验证的测试

base_url=https://api.deepseek.com/v1
api_key=sk-xxxxxxxxxxxxxxxx
model=deepseek-chat
prompt=1+1等于几？请只回答数字
check=2
cspm=100

5.3 正则内容验证

base_url=https://api.deepseek.com/v1
api_key=sk-xxxxxxxxxxxxxxxx
model=deepseek-chat
prompt=请描述一下太阳
check=/太阳.+恒星/

5.4 长文本生成测试

base_url=https://api.deepseek.com/v1
api_key=sk-xxxxxxxxxxxxxxxx
model=deepseek-chat
prompt=请写一篇500字的关于云计算的短文
timeout=300000
readtimeut=60000

九、注意事项

流式响应依赖：插件强制使用 stream=true，若目标 API 不支持 SSE（Server-Sent Events）流式返回，将无法正确解析内容，可能导致 699001（Token 数为 0）。

Token 计数差异：流式估算的 Token 数与官方 usage 的计数方式不同，对比时请区分 stage 11/12（估算）与 stage 15（基于官方 completion_tokens）。

readtimeut 拼写：配置键名为 readtimeut（缺少字母 o），请严格按此拼写，否则将使用默认值 30000。该值检测的是 SSE 数据块之间的静默时间，非整体超时。

cspm 的合理取值：若模型本身的内容生成远快于推理（如某些轻量模型），cspm=100 可能误报。建议先通过调试模式观察正常比例后再设定阈值。

回调线程安全：所有回调均在内部网络 / 解析线程中触发，宿主程序需保证回调函数的线程安全。

DeepSeek 插件配置说明

一、概述#

二、输入配置参数详解#

2.1 API 连接参数#

2.2 请求内容参数#

2.3 超时与网络参数#

2.4 验证与质量控制参数#

三、输出指标详解#

3.1 数值性能指标#

3.2 文本与诊断信息#

3.3 错误码#

四、速度计算与校验逻辑#

4.1 Token 计数方式#

4.2 cspm 校验示例#

五、典型配置示例#

5.1 基础 DeepSeek API 测试#

5.2 带内容验证的测试#

5.3 正则内容验证#

5.4 长文本生成测试#

九、注意事项#