企业官网建设流程全解析

• 人工智能
• AI 应用

在 Zotero PDF2zh 中，每个 LLM 翻译服务（OpenAI、DeepSeek、Ollama、Azure OpenAI、SiliconFlow、Qwen MT 等）都由三部分配置构成：基础字段（model、url、apiKey）与额外字段（extraData）。本文以仓库中的 extraData.md 为骨架，结合插件端与 Server 端源码，系统讲解每个服务可用的额外字段、字段如何从插件界面传递到翻译运行时，以及 DeepSeek V4 思考模式在 Server 中的完整执行策略。读完本文，你将能熟练地为任意翻译服务填写正确的额外参数，并理解参数被忽略或翻译被中止时的底层原因。

一、extraData 机制是什么

extraData是 Zotero 插件与 PDF2zh Server 之间传递 LLM 服务非通用配置的通用通道。通用配置固定为三个基础字段：

其中部分字段可以为空（例如自托管 Ollama 不需要密钥、DeepLX 的 token 可选）。除这三个字段外，不同服务往往还有各自的专属参数——比如 OpenAI 的temperature、DeepSeek 的思考模式、Ollama 的最大 token 数等——这些参数统一通过extraData（一组key=value对）从插件传入 Server，再由 Server 按服务映射写入底层配置文件。

在插件端，extraData是LLMApiData接口的标准成员，与apiKey、apiUrl、model平级，见 llmApiManager.ts。Server 端在 config.py 中将其从请求体中取出并挂载到llm_api对象上：

self.llm_api = { 'apiKey': request_data.get('llm_api', {}).get('apiKey', ''), 'apiUrl': request_data.get('llm_api', {}).get('apiUrl', ''), 'model': request_data.get('llm_api', {}).get('model', ''), 'extraData': request_data.get('llm_api', {}).get('extraData', {}) }

需要强调的是：插件界面上的下拉框（如 DeepSeek 思考模式）只是帮助减少手工输入和非法值的辅助控件，数据依然走extraData机制保存与传递，并不存在另一套传参协议。

二、字段的完整数据流

理解 extraData 字段的意义，先要看清它从填表到生效的完整链路：

1. 插件表单：用户在 Zotero 的 LLM API 编辑界面填写基础字段与额外字段，保存为LLMApiData（含extraData对象），由 llmApiManager.ts 的updateLLMApi管理；
2. 请求传输：翻译任务发起时，插件把llm_api（含extraData）连同其他参数 POST 给本地 Server；
3. Server 解析：config.py 的Config类读取请求，将extraData存入self.llm_api；
4. 配置落盘：根据引擎不同，update_config_file 会把基础字段和 extraData 映射后写入config.json（pdf2zh 1.x 引擎）或config.toml（pdf2zh_next 引擎）；
5. 命令行执行：execute.py 组装最终命令并调用prepare_deepseek_runtime_command等钩子，把配置翻译成上游 CLI 参数后启动翻译进程。

字段与底层配置的映射关系定义在 config_map.py：pdf2zh_config_map面向旧引擎（映射为大写环境变量，如OPENAI_API_KEY、OLLAMA_HOST），pdf2zh_next_config_map面向新引擎（映射为config.toml中<service>_detail段的小写字段，如openai_api_key、ollama_host）。额外字段正是通过每个服务的extraData键列表登记在案的，例如：

"openai": { apiKey: "openai_api_key", model: "openai_model", apiUrl: "openai_base_url", extraData: [ 'openai_temperature', 'openai_reasoning_effort', 'openai_send_temprature', # 上游保留的历史拼写 'openai_send_reasoning_effort' ] },

在 config.py 中，extraData中的每个键值对都会被逐个写入 translator 配置，同时记录进translator_keys白名单；凡是不在白名单内的旧字段会在写回时被清理删除，从而避免脏配置残留。

三、OpenAI 服务字段

OpenAI 服务（pdf2zh_next 引擎下服务名为openai）的基础字段与额外字段如下：

基础字段

• openai_model：模型名称
• openai_base_url：API 地址
• openai_api_key：API 密钥

额外字段

⚠️拼写兼容陷阱：pdf2zh_next <= 2.9.0有意保留了openai_send_temprature这个历史错误拼写（temprature 而非 temperature）以兼容旧配置。因此原生 OpenAI 服务必须使用错误拼写openai_send_temprature，而 OpenAI 兼容服务（openaicompatible）则使用正常拼写openai_compatible_send_temperature。这一约定同时体现在 config_map.py 与 config.toml.example 的注释中。

示例配置：

openai_temperature=0.3 openai_send_temprature=true

四、DeepSeek 服务字段与 V4 思考模式（重点）

DeepSeek 是 extraData 机制中最复杂也最值得展开的服务，因为 V4 模型（deepseek-v4-pro/deepseek-v4-flash）新增了显式思考控制。

基础字段

• deepseek_model：模型名称
• deepseek_api_key：API 密钥

额外字段

插件的 DeepSeek 配置界面仍使用extraData机制保存这些字段，下拉框只负责减少手工输入和非法值。在插件端，llmApiEditorEnhancements.js 还实现了旧模型自动迁移：旧的deepseek-chat自动迁移为deepseek-v4-flash（思考关闭），旧的deepseek-reasoner自动迁移为deepseek-v4-flash（思考开启、effort=high）。

为什么默认关闭思考模式

开启思考模式会产生额外的 reasoning token 与费用，因此 Zotero PDF2zh 默认将deepseek_thinking_mode归一化为disabled。这也是 config.toml.example 中deepseek_detail段默认模型为deepseek-v4-flash的原因之一。

Server 端的实际执行策略

根据 extraData.md 与 deepseek_thinking.py，Server 对 DeepSeek V4 思考控制的执行策略可以归纳为：

1. 显式归一化：DeepSeek V4 没有显式 thinking 设置时，自动归一化为disabled，避免依赖 provider 默认行为；
2. CLI 参数生成：pdf2zh_next 2.9.0会从同名设置字段生成--deepseek-thinking-mode/--deepseek-reasoning-effortCLI 参数；
3. 按实际运行时检测：Server 在 API 调用前检查本次实际执行的pdf2zh_next/ Windows exe 的--help（或对 Python 环境做静态能力检查），而不是只检查某个环境中的版本字符串；
4. 支持时透传：运行时支持时，将 extraData 中的用户选择转换成上述上游 CLI 参数后执行；
5. 不支持时中止：运行时不支持时，在翻译/API 调用前直接停止，并提示用户运行python update_packages.py，不会静默忽略 thinking 设置；
6. 非 V4 模型不发送 V4-only 参数；
7. 清理临时字段：如果旧运行时不支持这些字段，Server 会清理共享config.toml中临时写入的 thinking 字段，避免影响其他服务。

关键点在于：thinking 参数是否存在由pdf2zh_next决定，不由 BabelDOC 版本决定。pdf2zh_next 2.8.2没有这些字段，2.9.0才新增；BabelDOC / PyMuPDF 的版本问题属于 PDF parser 与依赖兼容问题，与思考控制无关。

源码级实现印证

• deepseek_thinking.py 的normalize_deepseek_extra_data：非 V4 模型直接移除 thinking 字段；V4 模型校验enabled/disabled与high/max，非法值直接抛ValueError；
• deepseek_thinking.py 的_runtime_supports_thinking：对 uv/conda/system Python 通过 distribution 元数据静态检查（不启动重型 CLI），对不可检视的独立可执行文件（如 Windows 打包 exe）才回退到--help探测；
• deepseek_thinking.py 的prepare_deepseek_runtime_command：在execute_with_progress中于命令执行前被调用（见 execute.py），负责校验、清理 config 中过期字段并把 CLI 参数追加进最终命令；
• environment_lifecycle.py 的runtime_supports_deepseek_thinking：用importlib.metadata检查已安装pdf2zh-next的源码文件，确认同时存在deepseek_thinking_mode/deepseek_reasoning_effort字段与 CLI 下划线转连字符映射。

上游 CLI 示例

关闭思考（推荐作为默认配置）：

uv run pdf2zh_next input.pdf \ --deepseek \ --deepseek-model deepseek-v4-flash \ --deepseek-thinking-mode disabled \ --output ./output

开启思考，并选择 high 强度：

uv run pdf2zh_next input.pdf \ --deepseek \ --deepseek-model deepseek-v4-pro \ --deepseek-thinking-mode enabled \ --deepseek-reasoning-effort high \ --output ./output

当你在插件界面选择思考模式后，Server 实际生成的命令正是以上述 CLI 参数形态传给pdf2zh_next的。

五、Ollama 服务字段

Ollama 是本地模型服务，无需 API 密钥。

基础字段

• ollama_model：模型名称
• ollama_host：服务地址

额外字段

num_predict的默认值 2000 同时在 config.toml.example 的[ollama_detail]段体现。Ollama 对应的配置映射见 config_map.py。

六、Azure OpenAI 服务字段

基础字段

• azure_openai_model：模型名称
• azure_openai_base_url：API 地址
• azure_openai_api_key：API 密钥

额外字段

该默认版本号在 config.toml.example 的[azureopenai_detail]段可以看到。

七、SiliconFlow 服务字段

基础字段

• siliconflow_base_url：API 地址
• siliconflow_model：模型名称
• siliconflow_api_key：API 密钥

额外字段

在 config.toml.example 的[siliconflow_detail]段中，这两个字段的默认值均为false，另有一个额外的siliconflow_enable_json_mode字段。

八、Qwen MT 服务字段

Qwen MT（qwenmt）是阿里云的通义千问翻译模型。

基础字段

• qwenmt_model：模型名称
• qwenmt_base_url：API 地址
• qwenmt_api_key：API 密钥

额外字段

ali_domains是一个长提示字符串，用于指定翻译领域（如科学论文）。config.toml.example 中给出了面向科学论文的默认提示词，可在插件中按需替换。旧引擎 pdf2zh 1.x 下 Qwen MT 的对应环境变量为ALI_DOMAINS（见 config_map.py 与 config.json.example）。

九、OpenAI 兼容服务（openailiked / openaicompatible）

对于任意 OpenAI 兼容接口（如火山方舟 Ark），pdf2zh 1.x 引擎使用服务名openailiked，pdf2zh_next 引擎使用openaicompatible。

基础字段

• openai_compatible_model：模型名称
• openai_compatible_base_url：API 地址
• openai_compatible_api_key：API 密钥

额外字段

与原生 OpenAI 不同，兼容服务的 temperature 字段使用正常拼写。此外 config_map.py 与 config.toml.example 还登记了openai_compatible_enable_json_mode字段，示例服务入口见 config.json.example（OPENAILIKED_BASE_URL/OPENAILIKED_MODEL）。

十、与配置文件的对照关系

所有额外字段最终都会落到 Server 的配置文件里，你可以据此自查配置是否正确生效：

• pdf2zh_next 引擎：config.toml.example 中每个服务对应一个<service>_detail段，字段名与 extraData 键名一致。例如[openai_detail]段含openai_temperature、openai_reasoning_effort、openai_send_temprature、openai_send_reasoning_effort；[deepseek_detail]段含deepseek_thinking_mode、deepseek_reasoning_effort。
• pdf2zh 1.x 引擎：config.json.example 中每个服务在translators数组里对应一个envs字典，字段名是大写环境变量形式。

Server 在写回配置时会执行白名单清理（见 config.py）：凡是本次请求未携带、且不在config_map登记范围内的旧键都会被删除，所以配置文件里只会保留当前有效的字段。

十一、使用建议与排错清单

1. 布尔值统一使用true/false（字符串形式），插件与 Server 均按此解析；
2. 可选参数不确定时留空，使用上游默认值，避免传错值导致请求被拒；
3. 遇到参数被拒绝时，同时核对当前pdf2zh_next版本与字段拼写——特别是 OpenAI 的openai_send_temprature历史拼写问题；
4. DeepSeek V4 思考模式不生效或被中止时，先确认pdf2zh_next是否 ≥ 2.9.0，必要时在 server 目录运行python update_packages.py更新翻译环境；不要误以为这是 BabelDOC 或 PyMuPDF 的问题；
5. 日志中若出现意料之外的请求端点（如 DeepLX 请求打到了https://api.deepl.com/v2/translate），检查实际选择的服务是deeplx还是deepl；
6. 配置后立即翻译验证：Server 启动时会打印去敏后的配置摘要（API Key 仅显示末四位），可据此确认extraData是否正确写入。

相关文档

• extraData 字段原始说明
• 额外参数中文指南
• 配置说明
• 翻译环境更新
• 翻译服务 FAQ

• 人工智能
• AI 应用