人工智能AI 应用【免费下载链接】zotero-pdf2zhPDF2zh for Zotero | Zotero PDF中文翻译插件项目地址https://gitcode.com/gh_mirrors/zo/zotero-pdf2zh点击查看免费下载在 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 服务非通用配置的通用通道。通用配置固定为三个基础字段基础字段含义model模型名称urlapiUrlAPI 地址Base URLapiKeyAPI 密钥其中部分字段可以为空例如自托管 Ollama 不需要密钥、DeepLX 的 token 可选。除这三个字段外不同服务往往还有各自的专属参数——比如 OpenAI 的temperature、DeepSeek 的思考模式、Ollama 的最大 token 数等——这些参数统一通过extraData一组keyvalue对从插件传入 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 字段的意义先要看清它从填表到生效的完整链路插件表单用户在 Zotero 的 LLM API 编辑界面填写基础字段与额外字段保存为LLMApiData含extraData对象由 llmApiManager.ts 的updateLLMApi管理请求传输翻译任务发起时插件把llm_api含extraData连同其他参数 POST 给本地 ServerServer 解析config.py 的Config类读取请求将extraData存入self.llm_api配置落盘根据引擎不同update_config_file 会把基础字段和 extraData 映射后写入config.jsonpdf2zh 1.x 引擎或config.tomlpdf2zh_next 引擎命令行执行execute.py 组装最终命令并调用prepare_deepseek_runtime_command等钩子把配置翻译成上游 CLI 参数后启动翻译进程。字段与底层配置的映射关系定义在 config_map.pypdf2zh_config_map面向旧引擎映射为大写环境变量如OPENAI_API_KEY、OLLAMA_HOSTpdf2zh_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_urlAPI 地址openai_api_keyAPI 密钥额外字段字段说明openai_temperatureOpenAI 服务的 Temperature随机性控制openai_reasoning_effort推理强度可选minimal/low/medium/highopenai_send_temprature是否将 temperature 发送给服务openai_send_reasoning_effort是否将 reasoning effort 发送给服务⚠️拼写兼容陷阱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_temperature0.3 openai_send_tempraturetrue四、DeepSeek 服务字段与 V4 思考模式重点DeepSeek 是 extraData 机制中最复杂也最值得展开的服务因为 V4 模型deepseek-v4-pro/deepseek-v4-flash新增了显式思考控制。基础字段deepseek_model模型名称deepseek_api_keyAPI 密钥额外字段字段说明取值deepseek_enable_json_mode是否启用 JSON mode依pdf2zh_next配置deepseek_thinking_modeDeepSeek V4 思考模式disabled/enableddeepseek_reasoning_effortDeepSeek V4 思考强度high/max仅在deepseek_thinking_mode enabled时生效插件的 DeepSeek 配置界面仍使用extraData机制保存这些字段下拉框只负责减少手工输入和非法值。在插件端llmApiEditorEnhancements.js 还实现了旧模型自动迁移旧的deepseek-chat自动迁移为deepseek-v4-flash思考关闭旧的deepseek-reasoner自动迁移为deepseek-v4-flash思考开启、efforthigh。为什么默认关闭思考模式开启思考模式会产生额外的 reasoning token 与费用因此 Zotero PDF2zh 默认将deepseek_thinking_mode归一化为disabled。这也是 config.toml.example 中deepseek_detail段默认模型为deepseek-v4-flash的原因之一。Server 端的实际执行策略根据 extraData.md 与 deepseek_thinking.pyServer 对 DeepSeek V4 思考控制的执行策略可以归纳为显式归一化DeepSeek V4 没有显式 thinking 设置时自动归一化为disabled避免依赖 provider 默认行为CLI 参数生成pdf2zh_next 2.9.0会从同名设置字段生成--deepseek-thinking-mode/--deepseek-reasoning-effortCLI 参数按实际运行时检测Server 在 API 调用前检查本次实际执行的pdf2zh_next/ Windows exe 的--help或对 Python 环境做静态能力检查而不是只检查某个环境中的版本字符串支持时透传运行时支持时将 extraData 中的用户选择转换成上述上游 CLI 参数后执行不支持时中止运行时不支持时在翻译/API 调用前直接停止并提示用户运行python update_packages.py不会静默忽略 thinking 设置非 V4 模型不发送 V4-only 参数清理临时字段如果旧运行时不支持这些字段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非法值直接抛ValueErrordeepseek_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最大预测 token 数2000num_predict的默认值 2000 同时在 config.toml.example 的[ollama_detail]段体现。Ollama 对应的配置映射见 config_map.py。六、Azure OpenAI 服务字段基础字段azure_openai_model模型名称azure_openai_base_urlAPI 地址azure_openai_api_keyAPI 密钥额外字段字段说明azure_openai_api_versionAPI 版本如2024-06-01该默认版本号在 config.toml.example 的[azureopenai_detail]段可以看到。七、SiliconFlow 服务字段基础字段siliconflow_base_urlAPI 地址siliconflow_model模型名称siliconflow_api_keyAPI 密钥额外字段字段说明siliconflow_enable_thinking启用思考模式siliconflow_send_enable_thinking_param是否向服务发送思考模式参数在 config.toml.example 的[siliconflow_detail]段中这两个字段的默认值均为false另有一个额外的siliconflow_enable_json_mode字段。八、Qwen MT 服务字段Qwen MTqwenmt是阿里云的通义千问翻译模型。基础字段qwenmt_model模型名称qwenmt_base_urlAPI 地址qwenmt_api_keyAPI 密钥额外字段字段说明ali_domainsQwen MT 的领域/上下文提示词ali_domains是一个长提示字符串用于指定翻译领域如科学论文。config.toml.example 中给出了面向科学论文的默认提示词可在插件中按需替换。旧引擎 pdf2zh 1.x 下 Qwen MT 的对应环境变量为ALI_DOMAINS见 config_map.py 与 config.json.example。九、OpenAI 兼容服务openailiked / openaicompatible对于任意 OpenAI 兼容接口如火山方舟 Arkpdf2zh 1.x 引擎使用服务名openailikedpdf2zh_next 引擎使用openaicompatible。基础字段openai_compatible_model模型名称openai_compatible_base_urlAPI 地址openai_compatible_api_keyAPI 密钥额外字段字段说明openai_compatible_temperature随机性控制openai_compatible_reasoning_effort推理强度openai_compatible_send_temperature是否发送 temperatureopenai_compatible_send_reasoning_effort是否发送 reasoning effort与原生 OpenAI 不同兼容服务的 temperature 字段使用正常拼写。此外 config_map.py 与 config.toml.example 还登记了openai_compatible_enable_json_mode字段示例服务入口见 config.json.exampleOPENAILIKED_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登记范围内的旧键都会被删除所以配置文件里只会保留当前有效的字段。十一、使用建议与排错清单布尔值统一使用true/false字符串形式插件与 Server 均按此解析可选参数不确定时留空使用上游默认值避免传错值导致请求被拒遇到参数被拒绝时同时核对当前pdf2zh_next版本与字段拼写——特别是 OpenAI 的openai_send_temprature历史拼写问题DeepSeek V4 思考模式不生效或被中止时先确认pdf2zh_next是否 ≥ 2.9.0必要时在 server 目录运行python update_packages.py更新翻译环境不要误以为这是 BabelDOC 或 PyMuPDF 的问题日志中若出现意料之外的请求端点如 DeepLX 请求打到了https://api.deepl.com/v2/translate检查实际选择的服务是deeplx还是deepl配置后立即翻译验证Server 启动时会打印去敏后的配置摘要API Key 仅显示末四位可据此确认extraData是否正确写入。相关文档extraData 字段原始说明额外参数中文指南配置说明翻译环境更新翻译服务 FAQ赞分享人工智能AI 应用【免费下载链接】zotero-pdf2zhPDF2zh for Zotero | Zotero PDF中文翻译插件项目地址https://gitcode.com/gh_mirrors/zo/zotero-pdf2zh点击查看免费下载相关推荐ToastFishWindows通知栏背单词免费玩法3步弹出你的第一个单词ToastFishWindows通知栏背单词免费玩法3步弹出你的第一个单词 ToastFish 是一款完全开源免费的 Windows 通知栏背单词 软件把人工智能AI 应用Zotero PDF2zh 快速入门从零安装 Server、插件与翻译服务配置Zotero PDF2zh 快速入门从零安装 Server、插件与翻译服务配置 本篇指南面向 Zotero 用户与科研读者讲解 Zotero PDF2zh人工智能AI 应用Zotero PDF2zh v4.1.1 安装部署指南Server 下载、翻译环境托管与 Zotero 插件配置Zotero PDF2zh v4.1.1 安装部署指南Server 下载、翻译环境托管与 Zotero 插件配置 本指南面向 Zotero PDF2zhZo人工智能AI 应用上一篇5个关键策略构建高性能MinecraftForge模组服务器的实战指南下一篇攻克TypeScript类型难题RequiredByKeys工具实现指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考