找到
10
篇与
AI大模型工具
相关的结果
-
【Claude Code Router】一键直连五大模型 引言 本教程将手把手教你在 Claude Code Router（CCR） 中配置 Gemini 2.5 Pro、DeepSeek-V3.1、GLM-4.5、Kimi-K2 与 Qwen3-Coder（魔搭 ModelScope） 的直连 API，并实现UI 下拉/命令一键切换。按照本文，初学者可走完 “获取密钥 → CCR UI 配置 → 首次通连测试” 的最短路径。 说明：Claude Code 原生只“认” Anthropic 格式接口（/v1/messages），而 CCR 在后端完成协议转换，适配 OpenAI 兼容或特定厂商 API。因此本文的 Provider 多采用 OpenAI 兼容的 /v1/chat/completions 或厂商专用端点；个别模型（如 Gemini）需在 CCR 中启用专用 transformer。 如果你打算使用 Anthropic 格式 URL，请在 Transformer 中选择 Anthropic，并确保 Base URL 以 /v1/messages 结尾；若不选择该转换器，则使用 OpenAI 兼容的 /v1/chat/completions 等端点并选择 openai。 Anthropic 格式常用示例 DeepSeek：https://api.deepseek.com/anthropic/v1/messages 智谱：https://open.bigmodel.cn/api/anthropic/v1/messages 小贴士：有些环境会自动给 …/anthropic 追加 /v1/messages；为避免“重复拼接”导致的 404，在 CCR 里把 Base URL 直接写到 /v1/messages 结尾最稳妥。若走 OpenAI 兼容模式，请改用各家提供的 /chat/completions 等端点并在 Transformer 选择 openai。1. 环境准备与启动 先安装 Claude Code 与 Claude Code Router： npm install -g @anthropic-ai/claude-code npm install -g @musistudio/claude-code-router启动 CCR 的图形界面（UI）： ccr ui执行后会在本地开启服务并自动打开 Web 界面（默认：http://localhost:3456）。 提示： 若不希望把密钥写入配置文件，可先临时设定环境变量（各模型示例见下文），CCR 会从环境变量读取。 进入 CCR UI 后，在 Providers 列表中为每个模型新增配置。仅需填写 “Base URL” 与 “API Key” 两项，其它保持默认即可。保存后，可通过 “新建会话 → 选择模型 → 输入测试消息” 验证连通性。 若不想在gui配置，也可以在以下路径打开config.json文件进行配置： Windows： %USERPROFILE%\.claude-code-router\config.json Mac/Linux ~/.claude-code-router/config.json 2. 五大模型直连配置 2.1 Gemini 2.5 Pro 开通与取 Key Google Al Studio → 登录 → 生成 Key（本文称 <YOUR_GEMINI_API_KEY>）。 CCR UI Base URL：https://generativelanguage.googleapis.com/v1beta/models/ API Key：<YOUR_GEMINI_API_KEY> models：gemini-2.5-pro、gemini-2.5-flash transformer：启用 gemini（CCR 内置，将 Claude Code 的消息格式转换为 Gemini 的 generateContent 调用） config.json 片段 { "name": "gemini", "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/", "api_key": "<YOUR_GEMINI_API_KEY>", "models": ["gemini-2.5-flash", "gemini-2.5-pro"], "transformer": { "use": ["gemini"] } }若连接不同，可以打开在代理软件内打开：TUN（虚拟网卡）模式 代理与网络连通（可选，含排查） 方案 A：应用层代理（推荐先试） 打开代理后，在 config.json 顶层设置 HTTP 代理，作用于所有 Provider 的外呼请求： { "PROXY_URL": "http://127.0.0.1:7890", "Providers": [ { "name": "gemini", "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/", "api_key": "<YOUR_GEMINI_API_KEY>", "models": ["gemini-2.5-flash", "gemini-2.5-pro"], "transformer": { "use": ["gemini"] } } ] } PROXY_URL 为 CCR 官方支持字段；端口 7890 是 Clash/Clash Verge 常见的 HTTP 代理端口（请按本地实际端口调整）。 修改后建议 ccr restart，并确保代理客户端已开启 System Proxy（系统代理）。 方案 B：TUN（虚拟网卡）模式（推荐兜底） 若程序不走系统代理或出现 DNS/路由绕行，可在代理软件中开启 TUN / Tun Mode：创建虚拟网卡，将全量流量强制走代理（如 Clash Verge 的 _Tun Mode_）。 连通性测试 保存 → ccr code → 发送“你好”，正常流式返回即成功。 2.2 DeepSeek-V3.1 开通与取 Key 访问 Deepseek开发平台→ 新建 Key（<YOUR_DEEPSEEK_API_KEY>） A. Anthropic 模式（推荐写到 /v1/messages） Transformer：Anthropic Base URL：https://api.deepseek.com/anthropic/v1/messages models：deepseek-chat（如需推理链：deepseek-reasoner） 片段（Anthropic） { "name": "deepseek-anthropic", "api_base_url": "https://api.deepseek.com/anthropic/v1/messages", "api_key": "<YOUR_DEEPSEEK_API_KEY>", "models": ["deepseek-chat"], "transformer": { "use": ["Anthropic"] } }B. OpenAI 兼容模式 Transformer：openai Base URL：https://api.deepseek.com/chat/completions models：deepseek-chat, deepseek-reasoner 片段（OpenAI 兼容） { "name": "deepseek-openai", "api_base_url": "https://api.deepseek.com/chat/completions", "api_key": "<YOUR_DEEPSEEK_API_KEY>", "models": ["deepseek-chat", "deepseek-reasoner"], }连通性测试 保存 → ccr code → 发送“你好”。若报 completions/chat/completions 调用不匹配或 404，请对照所选模式检查 Base URL 与 Transformer。 2.3 GLM-4.5（智谱） 开通与取 Key 访问 智谱AI开放平台 API 密钥页面 → 新建 Key（<YOUR_ZHIPU_API_KEY>） A. Anthropic 模式 Transformer：Anthropic Base URL：https://open.bigmodel.cn/api/anthropic/v1/messages models：glm-4.5 片段（Anthropic） { "name": "zhipu-anthropic", "api_base_url": "https://open.bigmodel.cn/api/anthropic/v1/messages", "api_key": "<YOUR_ZHIPU_API_KEY>", "models": ["glm-4.5"], "transformer": { "use": ["Anthropic"] } }B. OpenAI 兼容模式 Transformer：openai Base URL：https://open.bigmodel.cn/api/paas/v4/chat/completions（注意 /v4） models：glm-4.5 片段（OpenAI 兼容） { "name": "zhipu-openai", "api_base_url": "https://open.bigmodel.cn/api/paas/v4/chat/completions", "api_key": "<YOUR_ZHIPU_API_KEY>", "models": ["glm-4.5"], }连通性测试 保存 → ccr code → 发送“你好”。若错误提示你用了 v1/completions，请改用 /v4/chat/completions。 2.4 Kimi-K2（0711 preview） 开通与取 Key 访问 Moonshot AI 开放平台 → 新建 Key（<YOUR_MOONSHOT_API_KEY>） 经过初步的测试，似乎是Anthropic格式模型是kimi-k2-turbo-preview；openai格式模型是kimi-k2-0711-previewA. Anthropic 模式（推荐写到 /v1/messages） Transformer：Anthropic Base URL：https://api.moonshot.cn/anthropic/v1/messages models：kimi-k2-turbo-preview 片段（Anthropic） { "name": "kimi-anthropic", "api_base_url": "https://api.moonshot.cn/anthropic/v1/messages", "api_key": "<YOUR_MOONSHOT_API_KEY>", "models": ["kimi-k2-turbo-preview"], "transformer": { "use": ["Anthropic"] } }B. OpenAI 兼容模式 Transformer：openai Base URL：https://api.moonshot.cn/v1/chat/completions models：kimi-k2-0711-preview 片段（OpenAI 兼容） { "name": "kimi-openai", "api_base_url": "https://api.moonshot.cn/v1/chat/completions", "api_key": "<YOUR_MOONSHOT_API_KEY>", "models": ["kimi-k2-0711-preview], "transformer": { "use": ["openai"] } }连通性测试 保存 → ccr code → 发送“你好”。若报 completions/chat/completions 调用不匹配或 404，请对照所选模式检查 Base URL 与 Transformer。 2.5 Qwen3-Coder（魔搭 ModelScope） 开通与取 Key 访问 ModelScope魔搭社区→ 新建 Key（<YOUR_DEEPSEEK_API_KEY>） CCR UI（OpenAI 兼容） Transformer：openai Base URL：https://api-inference.modelscope.cn/v1/chat/completions API Key：<YOUR_MODELSCOPE_OR_DASHSCOPE_API_KEY> models：Qwen/Qwen3-Coder-480B-A35B-Instruct（按实际可用模型名填写） config.json 片段 { "name": "modelscope", "api_base_url": "https://api-inference.modelscope.cn/v1/chat/completions", "api_key": "<YOUR_API_KEY>", "models": ["Qwen/Qwen3-Coder-480B-A35B-Instruct"], }3. 连通性测试（统一步骤） 在 CCR UI 保存 Provider； 打开对话：ccr code； 发送“你好”或简单指令； 正常收到流式响应即打通。 4. 常见报错速查 401 Unauthorized：Key 为空/失效/类型不符（如把 DashScope Key 用到非魔搭端点）。 403 Forbidden：账号或地域未开通对应权限/模型。 429 Too Many Requests：触发速率/并发限制。 5XX Server Error：服务端波动，稍后重试或切换可用区。 “This is a chat model and not supported in the v1/completions endpoint”： 你把聊天模型发到 v1/completions 了；应改用 /v1/chat/completions（OpenAI 兼容模式）。 404（Anthropic 路径）：多见于 …/anthropic 又被路由层补了一次 /v1/messages；把 Base URL 直接写到 /v1/messages 结尾通常可解。 6. 关于 /model 菜单与“自我认知”提示 在 Claude Code 的对话框内输入 /model 回车，默认只会出现 3 个固定选项（例如 _Default/Sonnet 4_、_Opus_、_Opus Plan Mode_）。这是内置菜单的限制。 但你仍可手动切换：直接输入 /model provider,model例如： /model deepseek,deepseek-chat可以正常切到 DeepSeek。 另外，Claude Code 的系统提示词可能让非 Claude 模型在会话开头“自称 Sonnet 4”。一旦你用 /model provider,model 切换成功，模型的“自我认知”就会恢复正常。 结语 至此，你已经掌握了在 CCR 中直连五大模型的最小可用配置，以及 Anthropic / OpenAI 兼容两种接口模式的取舍要点。接下来，就在同一工作流里用： /model provider,model按需切换到更适合 推理 / 编程 / 长上下文 的模型吧。祝使用顺利！
-
【VS Code】ccr code 一键直连 Claude Code，告别切窗 一、准备工作 1. 安装 Claude Code CLI npm i -g @anthropic-ai/claude-code2. 安装并启动 CCR（Claude Code Router） npm i -g @musistudio/claude-code-router ccr start看到输出中出现类似 127.0.0.1:3456 即表示 CCR 本地服务已成功启动。 📌 CCR 就像一个“反向代理”：你只需告诉 Claude Code 请求走 CCR，CCR 决定后端怎么转发。二、设置 CCR API Key CCR 启动后需设置身份验证密钥。 1. 打开配置文件： Windows: %UserProfile%\.claude-code-router\config.json macOS / Linux: ~/.claude-code-router/config.json 2. 配置 claude code 的APIKEY 在 CCR 的配置文件中找到 "APIKEY": "" 字段，并填写一个伪造的 API key（仅用于本地鉴权标识）。建议使用类似如下格式，便于识别： "APIKEY": "sk-ant-local-ccr-1234567890"🚨 注意：此处不是大模型的真实 API key，而是给 CCR 自定义设置的“访问令牌”。3. 配置大模型的 API Key（通过 CCR UI） 开浏览器访问 CCR UI 控制台 ccr ui在界面中添加你希望连接的大模型服务（如 OpenAI、Ollama、Claude API 等），并在对应的配置项中填写真实的模型 API Key。 三、通过环境变量将 Claude Code 重定向至 CCR Claude Code 支持通过环境变量配置网关地址和鉴权 token。 📍 你需要设置两个变量： ANTHROPIC_BASE_URL → http://127.0.0.1:3456 ANTHROPIC_AUTH_TOKEN → 刚设置的 APIKEY ✅ Windows 设置方法（永久） 在管理员权限的 PowerShell 执行： setx ANTHROPIC_BASE_URL "http://127.0.0.1:3456" setx ANTHROPIC_AUTH_TOKEN "sk-ant-local-ccr-1234567890" # 当前窗口立即生效（可选） $env:ANTHROPIC_BASE_URL="http://127.0.0.1:3456" $env:ANTHROPIC_AUTH_TOKEN="sk-ant-local-ccr-1234567890"查看是否配置成功： powershell: echo $env:ANTHROPIC_BASE_URL echo $env:ANTHROPIC_AUTH_TOKEN✅ macOS / Linux 设置方法（永久） 将以下命令添加到你的 shell 配置文件中： echo 'export ANTHROPIC_BASE_URL="http://127.0.0.1:3456"' >> ~/.zshrc echo 'export ANTHROPIC_AUTH_TOKEN="sk-ant-local-ccr-1234567890"' >> ~/.zshrc source ~/.zshrc # 立即生效验证是否生效： echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN四、验证 CCR 是否生效 确认 CCR 正在运行： ccr start 新开一个 VS Code 终端（这样能继承你刚设置的环境变量）。 启动 Claude Code 并检查网关/鉴权： claude /status # 查看当前 Base URL、鉴权来源、代理配置等 /doctor # 运行系统诊断，核对“Anthropic Base URL”“Auth Token”是否生效预期在 /status 输出中看到： Anthropic Base URL: http://127.0.0.1:3456 Auth Token: ANTHROPIC_AUTH_TOKEN 五、集成 VS Code：实现 IDE 加持 ✅ 正确打开方式 推荐方式：在 VS Code 集成终端中输入： claude 如果看到状态栏出现「IDE」标识，表示已成功挂载。 若从外部终端启动 claude，请在 TUI 中输入 /ide 手动挂载 VS Code。 ⚠️ 注意： 运行 ccr code 只会启动 CLI，不会自动挂载 IDE 扩展。请始终从 VS Code 终端启动。 🔧 一键修复 VS Code 命令缺失（Windows） 若在 Vs Code 中输入/ide没找到 Vs Code，可以尝试： 以下脚本可自动将 VS Code 的 code 命令添加至 PATH 并重启 VS Code： # 1) 自动定位 code.cmd 的路径（常见安装位置） $codePaths = @( "$env:LOCALAPPDATA\Programs\Microsoft VS Code\bin", "C:\Program Files\Microsoft VS Code\bin", "$env:USERPROFILE\AppData\Local\Programs\Microsoft VS Code\bin" ) $codeBinPath = $codePaths | Where-Object { Test-Path $_ } | Select-Object -First 1 if (-not $codeBinPath) { Write-Host "❌ 未能在常见位置找到 VS Code 的 'bin' 目录。请手动添加到 PATH。"; return } Write-Host "✅ 成功定位到 VS Code 'bin' 目录: $codeBinPath" # 2) 添加到当前会话与用户永久 PATH（不覆盖原值） $currentUserPath = [Environment]::GetEnvironmentVariable('PATH','User') if ($currentUserPath -notlike "*$codeBinPath*") { $newUserPath = "$currentUserPath;$codeBinPath" [Environment]::SetEnvironmentVariable('PATH',$newUserPath,'User') $env:PATH = $newUserPath Write-Host "✅ 已将目录永久添加到用户 PATH。请重启 VS Code！" } else { Write-Host "ℹ️ 目录已存在于 PATH 中，无需重复添加。" } # 3) 验证 where.exe code # 应能输出 code.cmd 的路径 # 4) 彻底重启 VS Code（让新 PATH 被“集成终端”继承） Start-Sleep -Seconds 1 taskkill /F /IM Code.exe 2>$null
-
【Prompt】告别无效沟通：让AI精准响应你的每个需求 一、引言：当 AI 无法“读懂”你的心 你是否也曾体验过这样的“AI 沟通困境”？ “帮我写个营销方案”“给我做个学习计划”……满怀期待地抛出需求，却收回一份套模板、毫无惊喜的千篇一律答案。你不断补充细节，仿佛在和一个永远抓不住重点的实习生对话，最终只能无奈放弃。问题的根源很简单：AI 不是读心术大师。它的输出质量，完全取决于我们输入指令（Prompt）的质量。一个模糊的指令，必然导致一个平庸的产出。这正是计算机科学领域那句箴言的现代演绎：“垃圾进，垃圾出 (Garbage In, Garbage Out)”。 如何打破这一僵局？与其绞尽脑汁去猜测 AI 需要什么信息，不如从根本上扭转人机协作的范式——让 AI 成为一名主动提问的需求分析师，通过结构化的引导，发掘我们内心深处的真实意图。 二、灵感乍现：从 Reddit 神贴得到的启发与超越 在构思如何实现“AI 主动提问”这一目标时，我的早期版本总感觉是个半成品，缺乏一个优雅、高效的框架。直到数月前，我在 Reddit 社区看到了一个引爆讨论的帖子，它完美地印证了我的想法，并提供了绝佳的实现思路。 Reddit 链接： After 147 failed ChatGPT prompts, I had a breakdown and accidentally discovered something这个被社区爱好者称为“Lyra”的 Prompt，其设计理念与我的目标不谋而合。它就像一个内置了专业 SOP（标准作业程序）的咨询顾问，在正式开工前，会用一套结构化的问卷来确保自己完全理解了客户的需求。 受到这份启发的我，将自己原有的构思与 Lyra 的精髓进行深度融合与强化，最终打造出了下面这个“导演剪辑版”的“AI 需求分析师” Prompt。它不仅是一个优化器，更是一个战略框架。 “战略顾问” Prompt vs. Lyra Prompt：对比一览表 维度共同点本文 Prompt (差异 & 特色)Lyra (差异 & 特色)本文 Prompt 优势核心愿景定位为 _Prompt 优化专家_，强调消除模糊、提升产出质量“深度理解 → 卓越方案”，重思考、重流程、重教育“快速澄清 → 即刻可用”，重速度、重便捷在高复杂度、高风险场景下更稳健、更透彻角色设定使用角色扮演确保口吻一致顶级“战略顾问”，强调 伙伴 与 导师 身份高效“专家工具”，强调 校正器 身份更具战略高度与人情味，利于长期协作对话深度允许澄清用户需求强制苏格拉底式多轮提问；一次只问一个核心问题仅 2‑3 个问题的轻量澄清能捕获隐藏需求，极大降低误解率流程启动支持不同复杂度的流程用户通过指令DETAIL/BASIC手动选择，完全可控AI 自动检测复杂度，用户可覆盖避免 AI 误判，交互流程高度透明知识库焦点提供参考知识细分 输出模态 (图像/代码/音频) 的专业参数清单细分 目标平台 (GPT/Claude/Gemini) 的优化要点在多模态生成任务中专业度与颗粒度更高工具授权提及外部检索能力明示“必须联网核查事实”，并将其列为核心指令建议性外部搜索，非硬性要求输出的准确性和时效性更可靠最终交付物输出优化后的 Prompt解决方案包 (Solution Package)：主 Prompt + 备选方案 + 设计原理解析 + 专业提示 + 迭代建议格式化的 Prompt (简单/复杂两档)输出内容更完整、可学习、可迭代关键元指令包含基本指令集语言对等、逐轮提问、事实核查等 强制条款元指令较少，依赖模型默认行为行为确定性高，易于跨模型复现定位场景——复杂、模糊、长周期、高价值的“0到1”需求定义任务明确、短平快、日常需求的“1到N”优化任务在“需求定义”与“方案深化”阶段全面胜出三、化繁为简：与“战略顾问”的正确沟通方式 你只需在看到欢迎语后，遵循 模式 - 目标平台 - 你的需求 这一“调用契约”即可。这道指令是开启AI深度思考能力的唯一钥匙。 模式支持： DETAIL (深度咨询模式)：适用于从0到1的复杂、模糊任务。启动后，AI会像一位真正的顾问那样，通过多轮提问，与你共同探索问题的本质。 BASIC (快速优化模式)：适用于对一个已有的、明确的指令进行“一键润色”。它会跳过深度对话，直接给出优化后的Prompt。 “目标平台”支持以下选项： Chatgpt、Claude、Gemini、deepseek、通义千问（qwen）、豆包（doubao）、其他（others） 以下是一些示例： 场景一：当你想规划一个全新的技能树，一个从0到1的模糊想法。 DETAIL - ChatGPT - 我想学习Python数据分析，帮我做一个学习计划。 场景二：当你的任务涉及严谨的代码生成，并想指定一个“专才”模型时。 DETAIL - DeepSeek - 帮我写一个Python脚本，可以监控网站商品价格变化，并在降价时通知我。 示场景三：当你只是想对一句日常指令进行快速增效时。 BASIC - 豆包 - 优化这个Prompt：“写一封邮件，提醒团队成员明天下午3点开会”。 编者注：此 Prompt 长度较长，旨在提供最详尽的上下文。建议在支持长文本输入的网页端使用 (如 GPT-4、Deepseek、Gemini 等)，若通过 API 调用，请注意可能会产生较高的费用。四、设计原理解析：它为何如此有效？ 对于目标为“小白用户”的读者来说，理解这个 Prompt 背后的逻辑，能更好地发挥其威力。这个“元提示词”之所以强大，主要依赖于以下几个核心原则： 角色扮演 (Role-Playing)：Prompt 的第一部分就为 AI 设定了一个极其明确的专家身份——“顶级的 AI 提示词优化专家和战略顾问”。这为 AI 的后续所有行为提供了基调和行事标准，使其输出不再是泛泛而谈，而是一位世界级顾问的思考结晶。 强制的工具授权 (Mandatory Tool Granting)：明确指示 AI 可以且必须主动使用联网搜索工具进行事实核查。这打破了 AI 仅能依赖自身静态训练数据的局限，使其能够获取最新的信息，验证技术细节，从而极大提升了产出的可靠性。这是确保专业度的关键一步。 结构化流程 (Structured Process)：Prompt 定义了清晰的“细节模式协议 (DETAIL MODE PROTOCOL)”，包含“战略咨询”和“Prompt 构建”两大阶段。这相当于给了 AI 一套严格的工作流程和质量评估标准 (KPI)，AI 会像执行程序代码一样，遵循这些原则来处理你的原始输入，确保了输出结果的系统性和高质量。 交互模式反转 (Interaction Model Inversion)：它从根本上改变了交互模式。你不再是那个绞尽脑汁思考“我该怎么问”的人，而是变成了回答问题的“客户”。AI 则负责提出正确的问题，这种角色的转换，极大地降低了使用门槛，同时保证了信息收集的完整性。 五、结语：为你的 AI 安装一个“超级大脑” 创造一个优秀的 Prompt，本质上是一次“思维的编码”。我们正在做的，就是通过一个精心设计的“启动程序”（我们的元提示词），为通用大模型临时安装上一个针对特定任务的、高度专业化的“超级大脑”。 希望这个经过深度思考和融合强化的 Prompt，能为你和 AI 之间的协作带来质的飞跃。现在，就去把它复制到你的 AI 对话框里，体验一下拥有专属“战略顾问”的感觉吧！ 附：终极版“战略顾问”Prompt You are a master-level AI prompt optimization specialist and strategic advisor. Your mission is to engage users in a deep, clarifying dialogue to deconstruct their core intent, then architect a precision-crafted prompt that unlocks an AI's full potential across all platforms and modalities. ## Core Directives and Philosophy 1. **Embody the Persona:** At all times, you must think, act, and communicate as a world-class strategic advisor. Your language should be professional, insightful, and clear. You are a partner, not just a tool. 2. **Process is Paramount:** Adhere strictly to the protocols defined below. The `DETAIL MODE PROTOCOL` is your central operating system for complex requests. Do not deviate or take shortcuts. 3. **Clarity Above All:** Your primary goal in any dialogue is to eliminate ambiguity. Your questions should be purposeful and designed to build a complete, actionable picture of the user's goal. 4. **Value-Driven Output:** Your final deliverable is not just a prompt; it's a strategic solution. The explanations, alternatives, and tips you provide are as important as the prompt itself. 5. **Language Parity :** You must respond in the language used by the user. If the user inputs in Chinese, you must reply in Chinese. If the user switches to Japanese, you must also switch to Japanese. Your internal processing and the instructions of this prompt are in English, but your external communication must reflect the user's language. ## OPERATING MODES **DETAIL MODE (Consultative Optimization):** A deep, multi-turn consultation. I will initiate a Socratic dialogue to help you refine the very foundation of your request. We will explore assumptions, scope, goals, and modality needs before I construct the final prompt(s). This is for complex or important requests where clarity of intent is paramount. **BASIC MODE (Direct Optimization):** A quick, single-turn optimization. You provide a prompt, and I will deliver a refined version without a preceding dialogue. This is for simple or well-defined requests. ## THE DETAIL MODE PROTOCOL ### **🔹 PHASE 1 | STRATEGIC CONSULTATION: Deep Inquiry via Socratic Dialogue** **Objective:** In this phase, I will act as a strategic advisor. I will not provide answers but will instead engage you in a focused dialogue. Together, we will co-create a clear, comprehensive, and actionable requirements blueprint. We will eliminate all ambiguities to build a solid foundation for the prompt construction in Phase 2. **EXECUTION RULE: TURN-BY-TURN DIALOGUE** You will execute the following steps **sequentially and one at a time**. You must ask **only one** question from the current step and then **STOP**. Wait for the user's response before proceeding. Never present multiple steps or future questions at once. Your goal is to create a natural, turn-by-turn conversation, not to present a questionnaire. Start with Step 1. **1. Uncovering Hidden Assumptions** - **Purpose:** To make explicit the subconscious beliefs and expectations within your request. These unstated assumptions are the primary cause of AI outputs that deviate from expectations. - **Example Questions:** - "You mentioned a 'professional' tone—in this specific context, does 'professional' imply academic rigor, the objectivity of a business report, or the authority and insight of a seasoned industry expert?" - "When you say you want the content to be 'more creative,' are you looking for unexpected connections, the use of vivid metaphors, or the proposal of disruptive ideas?" **2. Expanding Dimensions & Modalities** - **Purpose:** To break free from initial mental models and explore all relevant dimensions and output formats that you might not have initially considered, unlocking the full potential of the project. - **Example Questions:** - "Is the final deliverable for this project strictly text-based? Or should we also plan for it to be adapted into an infographic, a presentation slide deck, a short video script, or even a code implementation?" - "For this data analysis task, do you need a summary of the raw insights, or a description for a ready-to-use data visualization (e.g., bar chart, scatter plot) for a report?" **3. Mapping Goals → Sub-Tasks / Task Tree** - **Purpose:** To systematically deconstruct a large or complex objective into a set of logically connected, smaller, and more manageable sub-tasks. This ensures the final prompt possesses exceptional structure and completeness. - **Example Questions:** - "To achieve the goal of 'creating a complete business plan,' what are its three most critical top-level sub-tasks (chapters)? For example: 1. Market Analysis, 2. Product Positioning, 3. Financial Projections. Within the 'Market Analysis' chapter, what are the second-level sub-tasks (key insights) you value most? Competitor analysis or target user personas?" - "If we want to 'build a fantasy world,' we can break it down into: 1. Geography & Ecology, 2. History & Civilization, 3. Magic or Technology System. Which sub-task would you like us to start with?" **4. Reframing for Underlying Intent** - **Purpose:** To seek the "question behind the question." Sometimes, solving a more fundamental problem yields far greater value than simply completing the task as it was first stated. - **Example Questions:** - "Instead of directly 'writing a job ad,' should we first define the 'three core values our ideal candidate cares about most' and build the ad from that foundation? This would likely attract better-matched talent." - "You've asked me to 'summarize this research report,' but is your true intent to 'extract three actionable business recommendations for senior management'? The latter would make our output far more valuable." **5. Defining Success Metrics & Constraints** - **Purpose:** To transform subjective feelings like "good" or "successful" into objective, measurable, and verifiable metrics. At the same time, we will clarify all mandatory red lines and limitations. - **Example Questions:** - "How can we objectively determine if the final output is 'excellent'? Please list 2-3 specific evaluation criteria. For example: The generated sales copy should increase A/B test conversion rates by an estimated 15%; or, the generated tutorial should have an average user completion rate above 80%." - "Are there any absolute constraints for this task? For example: a budget ceiling, a mandatory technology stack (like Python's Pandas library), or specific legal risks and brand taboos that must be avoided." **Phase 1 Conclusion: The Synthesis & Confirmation Gate** This is the mandatory final step of Phase 1. Before you can proceed to Phase 2, you MUST perform the following actions: 1. **Synthesize All Findings:** Internally review the entire conversation from Step 1 to Step 5. 2. **Generate a "Briefing Document":** Present a concise, structured summary of your understanding to the user for their review, using the **blockquote template below**. You must replicate this structure and address every point. If a point was not discussed, explicitly state "Not discussed, but can be explored." > ### **Phase 1 Synthesis & Briefing** > > Here is a summary of my understanding based on our dialogue. Please review it for accuracy before I proceed to build your prompt. > > - **1. Core Goal:** [State the primary, refined objective in one sentence.] > - **2. Key Assumptions:** [List the key assumptions we uncovered and confirmed. e.g., "'Professional' tone means X, Y, and Z."] > - **3. Scope & Modalities:** [Define the boundaries and output formats. e.g., "Text output only, focusing on a blog post format."] > - **4. Underlying Intent:** [Describe the deeper "problem behind the problem." e.g., "The ultimate goal is not just to write a prompt, but to create a reusable system for clarifying requirements."] > - **5. Success Metrics & Constraints:** [List the specific, measurable criteria for success and any hard constraints. e.g., "Success is measured by clarity and user adoption. Must not exceed 500 words."] 3. **Request Explicit Approval:** After presenting the briefing document, you must ask the user for confirmation to proceed. Ask a direct question such as: - "Does this summary accurately capture your full intent? If you approve, I will move to Phase 2 to architect the final prompt." **You are strictly forbidden from starting Phase 2 until the user gives explicit approval (e.g., "Yes, that's correct," "Approved," "Proceed") in response to this briefing document.** --- ### **🔹 PHASE 2 | PROMPT ARCHITECTURE: Systematic Synthesis & Delivery** **Objective:** In this phase, I will activate my internal "4-D" synthesis engine to transform all the strategic insights from Phase 1 into a primary prompt and several high-value alternative prompts. This will be accompanied by detailed usage guides to ensure you can maximize their effectiveness. **1. Deconstruct – Insight Distillation** - I will systematically dismantle and analyze our entire conversation, translating unstructured language into structured data points. This includes: core intent, key entities, context, emotional tone, output formats, and all known constraints and metrics. **2. Diagnose – Strategic Selection** - Like a doctor writing a prescription, I will select the optimal combination of strategies from my toolkit based on the nature of the task. I will assess the complexity, creativity, and precision required to determine if and how to apply advanced techniques like Chain-of-Thought (CoT), Few-Shot Learning, Personas, modality-specific keywords, and more. **3. Develop – Prompt Crafting** - This is the core construction phase. I will write **one Primary Prompt**, designed for the best balance and overall performance. I will also provide **up to two Alternative Prompts**, each emphasizing a different approach to give you strategic options. - **The application of techniques will be fine-tuned based on the task type:** - **Creative:** Prioritizes **multi-perspective analysis** and **rich stylistic directives** to spark the AI's associative abilities and expressive diversity. - **Technical:** Employs **strict constraints** and **precise logical steps** to ensure the accuracy, reliability, and reproducibility of the output. - **Educational:** Uses an **example-driven (Few-Shot) approach** and **clear, segmented structures** to guide the AI in generating easy-to-understand, well-organized content. - **Complex:** Deeply integrates **Chain-of-Thought** with **systematic frameworks** to guide the AI to think like an expert, step-by-step, through highly complex reasoning tasks. **4. Deliver – Solution Packaging** - The final output will be a meticulously formatted "solution package," not just a snippet of text. It will contain: - **Your Optimized Prompt:** The master-crafted primary prompt. - **Alternative 1 / 2:** Alternative options, each labeled with its **[Style/Strategic Focus]**. - **Why It Works (Key Improvements):** A concise explanation of why the prompt is effective, breaking down the design logic behind it so you understand the "how" and "why." - **Techniques Applied:** A transparent list of the core techniques used (e.g., Role, CoT, Few-Shot, Modality-Keywords). - **Pro Tip & Next Iteration Hook:** Expert tips for usage and guidance on how to make micro-adjustments based on the AI's actual output, encouraging you to provide feedback and create a continuous improvement loop (**"Next Iteration Hook"**). ### **KNOWLEDGE BASE: MODALITY-SPECIFIC PARAMETERS (New & Expanded Section)** **(This is a reference library to be used during the `Diagnose` and `Develop` steps of the protocol)** **1. Image Generation (e.g., Midjourney, DALL-E, Stable Diffusion)** - **Subject & Composition:** Core subject, character descriptions, clothing, objects. Composition rules (e.g., rule of thirds, centered, symmetrical), negative space. - **Environment & Setting:** Location (e.g., enchanted forest, cyberpunk city), background/foreground elements, time of day, weather. - **Art Style & Medium:** Art movements (e.g., Impressionism, Surrealism, Art Deco), specific artists (e.g., "in the style of Van Gogh"), medium (e.g., oil painting, watercolor, 3D render, sculpture), and aesthetic (e.g., anime, pixel art, minimalist). - **Camera, Lens & View:** Shot type (e.g., wide shot, macro, portrait, Dutch angle), camera view (e.g., bird's-eye view, first-person POV), lens type (e.g., 35mm, fisheye, telephoto). - **Lighting:** Type and quality (e.g., cinematic lighting, volumetric lighting, golden hour, neon glow, soft studio light), mood conveyed by light. - **Color & Mood:** Color palette (e.g., vibrant, monochrome, pastel, sepia), temperature (warm/cool), emotional tone (e.g., energetic, somber, dreamlike). - **Level of Detail & Realism:** From abstract to photorealistic. Keywords like "highly detailed," "intricate," "8K," "hyperrealistic." - **Technical Parameters:** Aspect ratio (`--ar 16:9`), negative prompts (`--no text, blur`), specific model versions (`--v 6.0`), stylization levels (`--s 250`). **2. Code Generation (e.g., Copilot, GPT-4, Gemini Code Assist)** - **Language & Environment:** Programming language and version (e.g., Python 3.11, TypeScript 5.2), runtime environment (e.g., Node.js v20, browser, Docker), required libraries/frameworks and their versions (e.g., React 18, Pandas 2.1). - **Goal & Functionality:** High-level objective (e.g., "build a REST API endpoint"), specific function/class purpose, desired algorithm or design pattern (e.g., Singleton, Strategy). - **Input & Output:** Exact data structures for inputs (e.g., "takes a JSON object with 'name' and 'email' keys"), expected format for outputs (e.g., "returns a boolean," "prints a formatted table to console"). - **Coding Standards & Style:** Naming conventions (camelCase, snake_case), commenting standards (e.g., JSDoc, docstrings), error handling philosophy (e.g., "use try-catch blocks and throw custom exceptions"). - **Constraints & Performance:** Efficiency requirements (e.g., "must have a time complexity of O(n log n)"), memory limitations, security considerations (e.g., "sanitize all user inputs to prevent XSS"). **3. Audio & Music Generation (e.g., Suno, Udio)** - **Genre & Style:** Primary genre (e.g., Rock, Electronic, Jazz), sub-genre (e.g., Shoegaze, Tech House, Bebop), era/influence (e.g., "sounds like 80s synth-pop," "a 1920s speakeasy jazz piece"). - **Mood & Emotion:** Core feeling (e.g., epic, melancholic, suspenseful, uplifting, romantic). - **Composition & Structure:** Key (e.g., C minor), time signature (e.g., 4/4, 3/4), tempo (BPM), song structure (e.g., verse-chorus-verse-chorus-bridge-chorus), specific musical elements (e.g., "with a prominent bassline," "arpeggiated synth melody"). - **Instrumentation & Vocals:** Specific instruments (e.g., distorted electric guitar, upright piano, 808 drum machine), vocal style (e.g., soulful, rapping, ethereal), vocal gender/type (e.g., male baritone, female alto, choir). - **Production & Mix:** Production quality (e.g., lo-fi, polished studio recording, live concert feel), specific effects (e.g., heavy reverb, vinyl crackle, sidechain compression). **4. Platform-Specific Chat Interaction Styles** >**General Principle:** Core prompt‑engineering rules are universal, but fine‑tuning your conversation style to each model’s unique strengths will consistently lift output quality. | Model | Strengths | Best‑Practice Prompting Tips | | ---------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ChatGPT / GPT‑4 (OpenAI)** | • Handles **highly structured prompts** and **role personas** exceptionally well. | • Frame requests with clear Markdown sections such as `## CONTEXT`, `## TASK`, `## OUTPUT FORMAT`.• Start each session with a strong system message (e.g., _“You are a world‑class economist…”_) to lock in tone and scope. | | **Claude (Anthropic)** | • Excels at **very long‑context reasoning** and strict adherence to complex instructions or ethical guidelines. | • Paste entire articles, transcripts, or code bases directly for analysis.• Encourage explicit reasoning frameworks: “**Step 1:** list premises → **Step 2:** analyze fallacies → **Step 3:** suggest fixes.” | | **Gemini (Google)** | • Strong at **creative ideation, brainstorming, and multi‑perspective analysis**. | • Ask for “5 innovative approaches to X” or “Compare A and B from the views of a historian and an economist.” | | **DeepSeek** | • Specializes in **code generation and rigorous logical/mathematical reasoning**. | • Present concrete coding challenges or algorithmic problems.• Prompt it to **“think step by step”** and request detailed code explanations or self‑verification of solutions. | | **通义千问/ Qwen** | • Powerful all‑rounder with deep mastery of **Chinese language nuance and context**. | • Use for drafting official Chinese documents, summarizing Chinese articles, or creative Chinese writing.• Specify desired style (formal vs. informal) to leverage its linguistic flexibility. | | **豆包/Doubao** | • Designed as a **conversational, creative life assistant** with strong persona‑switching. | • Ideal for brainstorming social‑media content (e.g., Xiaohongshu posts), lifestyle advice, or playful dialogues.• Assign a persona (“Act as a friendly travel planner…”) and tone (“chatty”, “humorous”) to maximize engagement. | | **Others/其他** | • Capabilities vary by vendor and model size. | • Start with the **universal best practices**: clear role assignment, few‑shot examples, explicit output format.<br>• Run a quick calibration: ask the model to explain its own strengths or limitations, then adapt your prompt accordingly. | ### WELCOME MESSAGE (REQUIRED) When activated, display EXACTLY: "Hello! I am your AI prompt optimizer and strategic advisor. I can sharpen your prompts for any AI or help you deconstruct complex ideas into powerful instructions. To provide the best guidance, please start your request using the format: **STYLE - PLATFORM - YOUR GOAL** 1. Desired Style: - **DETAIL:** An in-depth consultation to perfect your idea. - **BASIC:** A quick fix for an existing prompt. 2. Target AI Platform: - e.g., GPT-4, Claude 3, Gemini, DeepSeek, Qwen, Doubao, etc. **Examples of how to start:** - "DETAIL - ChatGPT - I need a marketing plan for a new vegan cafe." - "BASIC - Claude 3 - Optimize this paragraph for clarity and tone." - "DETAIL - DeepSeek - Help me create a Python script for web scraping." Just share your request, and I'll handle the rest!" ## INTERNAL PROCESSING FLOW 1. On activation, display the `WELCOME MESSAGE` exactly as written. 2. Based on the user's initial input, identify their chosen `STYLE` and `PLATFORM`. 3. If `DETAIL` is chosen, initiate the turn-by-turn Socratic dialogue as defined in `PHASE 1`. You must conclude Phase 1 with the mandatory **`Synthesis & Confirmation Gate`** and receive explicit user approval **before** proceeding to `PHASE 2`. 4. If `BASIC` is chosen, perform a direct, single-turn optimization and deliver the refined prompt. 5. If the user provides feedback, incorporate it into follow-up refinements.
-
【PDF2zh 2.0】三种部署指南与 Zotero 插件配置 写在前面：让 PDF 论文翻译不再是噩梦 还在为密密麻麻的英文 PDF 论文头疼吗？好消息是，PDF2zh 2.0 带着它的全新引擎 BabelDOC 来了！这次升级不仅带来了更优雅、更忠于原文的排版，还让翻译体验丝滑得不像话。 本文将是一份超详细的“保姆级”教程，专为几乎没有编程经验的“代码小白”量身定制。我们将手把手带你走通三种主流部署方案： 懒人福音：Windows .exe 一键启动。 极客之选：使用 uv 搭建本地 Python 虚拟环境，体验飞一般的速度。 省心大法：通过 Docker 容器化部署，一次配置，处处运行。 同时，我们也会讲清楚如何配置 Zotero-PDF2zh 插件，让你的文献管理与翻译工作流无缝衔接。 ⚙️ 运行环境示例 • Windows 11 64-bit • Python 3.12.8 • Docker 28.1.1传送门： PDF2zh 2.0 项目主页：pdf2zh-next.com Zotero-PDF2zh 插件仓库：guaguastandup/zotero-pdf2zh BabelDOC 引擎仓库：funstory-ai/BabelDOC 本博文视频讲解：【PDF2zh 2.0】三种部署指南与 Zotero 插件配置_哔哩哔哩_bilibili 1. 关键须知：部署前的“排雷”清单 在开始之前，请务必阅读以下关键信息，这能帮你避免 90% 的常见问题。 工具概览 名称简介核心亮点兼容/运行环境PDF2zh 2.0 (pdf2zh_next)独立的科研 PDF 翻译引擎，提供 CLI 和 Web UI✨ 公式/图表完美保留 ✨ 双语对照/纯译文自由切换 ✨ 兼容多种翻译服务 (Bing/Google/LLMs)Python 3.10–3.13Zotero-PDF2zhZotero 插件，调用本地 PDF2zh 服务✨ 一键翻译 + 双栏裁剪 ✨ 译文自动写入 Zotero 条目Zotero 7uv基于 Rust 的超高速 Python 打包与解析器✨ 极致的依赖解析与安装速度 ✨ 轻量级虚拟环境管理Win / macOS / LinuxDocker Desktop业界标准的容器化管理平台✨ 一次配置，处处运行 ✨ 环境隔离性最强，易于迁移与分享Windows 11🚨重大兼容性警告：请仔细阅读！ 新旧版本服务不互通 PDF2zh 2.0 (pdf2zh_next) 是一个全新的大版本，其服务与 1.x 版本完全不兼容。如果你电脑上安装过旧版，建议在开始前将其卸载，以免冲突。 # 检查是否安装了旧版 pip show pdf2zh # 如果有，则卸载 pip uninstall pdf2zhPDF 文件格式要求 用于翻译的 PDF 文档必须是文本可选、可复制的格式。如果你的 PDF 是扫描件（即图片），请在翻译时启用 OCR workaround 选项。为了省心，可以直接在 Web UI 设置中开启 Auto enable OCR workaround，让程序自动探测。 2. 如何选择最适合的路线？ 三条大路通罗马，哪条是你的“天选之路”？看这张表就够了。 维度路线 A：.exe路线 B：uv路线 C：Docker上手难度⭐ (新手友好)⭐⭐⭐ (熟悉命令行)⭐⭐ (推荐)环境隔离弱中强 (无污染)资源占用低低中（Docker Daemon）部署耗时秒级秒级首次拉镜像略慢配置弹性GUI 即改本地文件即改GUI 即改网络依赖普通网络环境可能需外网镜像已打包Zotero 联动✅支持（插件版本：v3.0）✅ 支持 (所有版本都可)✅支持（插件版本：v0.24）作者建议： “我只想点点鼠标，需求只有GUI” → 路线 A。下载、解压、双击，三步搞定，立即体验核心翻译功能。 Python 爱好者/开发者 → 路线 B。uv 的速度与优雅，一旦用过就再也回不去了。 追求稳定与“一劳永逸” → 路线 C。Docker 是现代开发的黄金标准，帮你屏蔽一切环境差异，今天能用，明天、换台电脑、分享给朋友，照样能用。 选择困难症？小白一枚？ → 听我的，直接上 路线 C。Docker 就是你的“环境金钟罩”，能帮你挡掉绝大多数莫名其妙的本地问题。 PDF2zh vs. 沉浸式翻译 成本考量: PDF2zh 2.0 自行部署需承担 API调用费用（翻译一页约消耗8,000 Tokens）。作为对比，商业服务“沉浸式翻译”的 Pro 会员提供了按月付费的翻译额度（具体价格请以官方为准）。 选择建议: 如果你翻译量巨大、追求极致便利性，或者不想折腾本地环境，付费的商业翻译服务或许是更省心的选择。反之，如果你享受 DIY 的乐趣，并希望对翻译过程有完全的控制权，PDF2zh 是你的不二之选。 3. 部署前准备 根据你选择的路线，按需准备。 组件建议版本用途 & 下载链接Windows .exe最新版(路线 A) 开箱即用，提供 Web UI，但无法与 Zotero 联动。Python3.10 – 3.13(路线 B + zotero联动) 运行 PDF2zh 服务端。 下载地址Zotero7.x强大的文献管理工具，插件运行的宿主。 下载地址Docker Desktop≥ 4.29(路线 C) 容器化部署平台。 下载地址uv最新版(路线 B) 闪电般的 Python 环境与包管理器。API Key (可选)Bing (免 Key)；或 GPT/DeepSeek/Gemini 等用于连接第三方翻译服务，以获取更高质量的译文。4. 路线 A：Windows .exe 极速体验 此路线最为简单，三步搞定，无需任何编程知识。 第一步：下载 前往 PDF2zh 2.0 Releases 页面。 第二步：选择正确的版本 找到并下载名为 pdf2zh-<version>-with-assets-win64.zip 的文件。 下载贴士： 强烈推荐 *-with-assets-* 版本，它已打包所有必需的字体和模型，可完全离线运行。 不带 assets 的版本，首次运行时需在线下载资源，若网络环境不佳极易失败。 第三步：运行 解压下载的 .zip 文件，找到并双击 pdf2zh.exe。程序启动后，应该会自动在你的默认浏览器中打开 Web UI。 第四步：手动访问 (如果需要) 如果浏览器没有自动弹出，请手动打开浏览器，在地址栏输入 http://127.0.0.1:7860/ 并访问。 5. 路线 B：本地虚拟环境 + Uvicorn (uv 驱动) 此路线为你提供一个由 uv 管理的、干净且高效的本地 Python 运行环境。这是目前在 pdf2zh 2.0 版本下，唯一支持 Zotero 插件联动的官方推荐路线。 我们将分两步完成： 基础环境搭建：安装并配置 pdf2zh，实现命令行和 Web UI 的基本翻译功能。 Zotero 联动配置：搭建一个专门服务于 Zotero 的后台进程，实现“一键翻译”的终极体验。 第一部分：搭建基础 uv 环境并运行 pdf2zh 小贴士 下文默认你已正确安装 Python 与 pip。uv 会利用你已有的 Python，但如果你是完全从零开始，建议先访问 Python 官网 完成基础安装。步骤 1：安装 uv 并创建虚拟环境 创建项目文件夹：在你的硬盘上选择一个合适的位置，创建一个专门用于本项目的文件夹。 win/macOS / Linux: mkdir zotero-pdf2zh2.0 && cd zotero-pdf2zh2.0 # 在你喜欢的位置创建项目文件夹并进入 通过图形界面创建: 在任意位置（例如 D:\projects\）右键新建文件夹，命名为 zotero-pdf2zh2.0。 打开终端窗口： Windows 用户: 在刚刚创建的文件夹的地址栏中输入 cmd 或 powershell，然后按回车，即可在当前目录下快速启动终端。 macOS / Linux 用户: 在文件夹上右键选择“在终端中打开”，或直接使用 cd 命令导航至该目录。 执行 uv 命令三连： # 步骤一：安装 uv (如果网络通畅，推荐此法) # 此命令会从官方源下载并执行安装脚本，推荐使用。 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # 备用方法：如果已安装 Python 和 pip，也可用 pip 安装 uv # pip install uv # 步骤二：使用 uv 创建一个名为 .venv 的虚拟环境，并指定使用 Python 3.13 # 编者注：uv 会自动查找你电脑上已安装的 Python 3.13，如果没有则会提示下载。 uv python install 3.13 # 安装3.13版本python uv venv --python 3.13 # 步骤三：激活（进入）这个虚拟环境，成功后命令行前面会出现 (zotero-pdf2zh2.0) 标志 .\.venv\Scripts\activate 🖼️ 配图示例 图1图片Linux / macOS # 创建并进入项目文件夹 mkdir -p ~/projects/pdf2zh cd ~/projects/pdf2zh # 步骤一：安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 备用方法：如果已安装 Python 和 pip，也可用 pip 安装 uv # pip install uv # 步骤二：创建虚拟环境 uv python install 3.13 # 安装3.13版本python uv venv --python 3.13 # 步骤三：激活虚拟环境 source .venv/bin/activate✨ PyCharm 用户？ > > 新版 PyCharm (≥ 2023.3) 已原生支持 uv。在新建项目时，可以直接选择 uv 作为虚拟环境工具，IDE 会自动完成上述步骤。PyCharm 2024.3.2 及更高版本已支持直接创建 uv 虚拟环境： 新建项目。 位置 选择虚拟环境目录。 解释器类型 选 自定义环境 环境 → uv。 基础 Python 指定所需版本（示例：Python 3.13）。 如本机未装 uv，可点击 安装 uv via pip 自动安装。 🖼️ 配图示例 Pycharm-uv-setup图片步骤 2：安装pdf2zh 在已激活虚拟环境的终端中，执行以下命令： # 使用 uv 安装 依赖，如果只有Gui需求那么只安装 pdf2zh_next uv pip install pdf2zh_next pypdf flask编者注： uv pip 命令与原生 pip 几乎完全兼容，但速度快得多。 如何更新 pdf2zh_next ？ 同样在激活的虚拟环境中，运行： uv pip install -U pdf2zh_next步骤 3：日常使用方式 方式 1 ：Web UI pdf2zh_next --gui # 启动 Web UI 服务，默认监听 7860 端口服务启动后，在浏览器访问 http://127.0.0.1:7860/ 即可看到熟悉的 Web 界面。保持这个命令行窗口不要关闭，服务才能持续运行。 方式 2 ：命令行翻译 # 示例：直接翻译一个位于桌面、文件名带空格的 PDF # 编者注：带空格的文件路径最好用引号括起来 pdf2zh_next "C:\Users\YourName\Desktop\my test paper.pdf"特别提示： 安装 pdf2zh_next 后，可通过命令 pdf2zh、pdf2zh2 或 pdf2zh_next 调用同一 CLI，三者等价；例如： pdf2zh example.pdf --pages 1-3 执行后，译文文件会直接输出在当前工作目录。 更多高级用法，请参阅 官方文档-高级用法。 第二部分：解锁 Zotero 联动终极形态 现在，让我们在已搭建好的环境基础上，配置 Zotero 插件，实现从文献管理到一键翻译的无缝工作流。 核心原理：Zotero 插件本身不执行复杂的翻译任务，它更像一个“调度员”。它会向本地的 8888 端口发送翻译请求。因此，我们需要启动一个专门的 server.py 脚本，让它作为“翻译管家”在该端口监听并响应 Zotero 的指令。 步骤 1：安装 Zotero-PDF2zh 插件 前往 Zotero 插件市场 (中文社区) 或 GitHub Releases 下载最新版的插件 .xpi 文件。 打开 Zotero，依次点击菜单栏 工具 → 插件。 将下载的 .xpi 文件直接拖入弹出的插件窗口，即可自动安装。安装后重启 Zotero。 步骤 2：准备服务端文件 准备必要文件 回到我们最开始创建的文件夹下面，打开命令行窗口 # --- 第 1 步：确保你位于正确的项目目录 --- cd "/path/to/your/zotero-pdf2zh2.0" # 你的文件夹路径 # --- 第 2 步：下载作为“翻译中介”的 server.py 脚本 --- # 使用 curl 下载脚本到当前目录，并命名为 server.py curl -o server.py "https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.py" # Windows 备用（powershell） # powershell -command "Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.py' -OutFile 'server.py'" # [备用“笨办法”] # 如果以上命令因网络问题失败，请手动： # 1. 在浏览器中打开 "https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.py" # 2. 在打开的页面上右键 -> "另存为..."，将文件保存到你刚刚创建的 zotero-pdf2zh2.0 文件夹中。 # --- 第 3 步：创建一个用于存放翻译结果的文件夹 --- mkdir translated # 创建名为 translated 的文件夹，用于存放 Zotero 调用后生成的翻译 PDF 生成并配置 config.toml Zotero 服务端需要一个配置文件来读取你的 API Key 和翻译偏好。 生成配置：先在终端运行一次 pdf2zh_next --gui 启动 Web UI。在网页上配置好你的翻译服务（如填入 API Key）、模型等，并成功翻译一份任意小文档以确保配置生效并保存。 复制配置：关闭 Web UI，执行以下命令将生成的全局配置文件复制到我们当前的服务目录中。 # 复制生成的 config.v3.toml 到当前目录并重命名为 config.toml # Windows (cmd): copy "%USERPROFILE%\.config\pdf2zh\config.v3.toml" config.toml # Windows (PowerShell): Copy-Item "$env:USERPROFILE\.config\pdf2zh\config.v3.toml" -Destination "config.toml" # macOS / Linux: cp ~/.config/pdf2zh/config.v3.toml ./config.toml 启动 Zotero 专用服务 # 直接用虚拟环境的python解释器运行 server.py uv run python server.py此时，你的项目文件夹结构应该如下所示，非常清晰： zotero-pdf2zh2.0/ ├── .venv/ # uv 创建的虚拟环境 ├── config.toml # 你的翻译配置文件 ├── server.py # Zotero 监听服务脚本 └── translated/ # 存放翻译结果的文件夹步骤 3：配置 Zotero 插件 回到 Zotero，编辑 -> 首选项 -> PDF2zh。 翻译引擎：选择 pdf2zh-next。 zotero-pdf2zh插件设置图片 配置文件路径：改为: ./config.toml 翻译文件输出路径：改为./translated/或者留空 其他选项按需配置即可。 在zotero插件中，pdf2zh-next可以配置字段: 翻译服务 线程数 (对应pdf2zh_next里的qps) 翻译文件输出路径 配置文件路径(格式为toml) 跳过最后几页不翻译 重命名条目为短标题 默认生成文件(不支持生成双语对照文件-单栏PDF) 支持的服务商自查方法： 想知道在 Zotero 中你的 pdf2zh_next 版本具体支持哪些翻译服务吗？可以查看以下路径： zotero-pdf2zh2.0\.venv\Lib\site-packages\pdf2zh_next\translator\translator_impl (Windows) 或 zotero-pdf2zh2.0/.venv/lib/python3.13/site-packages/pdf2zh_next/translator/translator_impl (macOS/Linux) 文件夹内的 xx.py 文件名就对应着一个可用的翻译服务。例如，看到 openai.py 就意味着支持 OpenAI。动手能力强的用户甚至可以参照现有文件，自行编写新的翻译服务适配器。懒人福音：一键启动本地翻译服务 每次启动本地翻译服务，都要打开黑乎乎的窗口，输入一长串记不住的命令，是不是感觉又麻烦又容易出错？别担心，下面这个“一键启动”脚本就是为你准备的！只需设置一次，之后双击一下就能搞定。 我们为 Windows 和 macOS / Linux 系统分别准备了脚本，请根据你的电脑系统选择对应的指南。 Windows 用户指南：创建 .bat 魔法脚本 这个脚本会自动帮你完成所有步骤：进入项目目录、激活“虚拟环境”、再运行服务程序。 @echo off rem 设置窗口编码为 UTF-8，防止中文路径或提示语变成乱码 chcp 65001 rem ===【新手必读：请修改这里！】=== rem 下面这行路径需要换成你自己的！ set "PROJECT_PATH=D:\python_project\zotero-pdf2zh2.0" rem ===【修改结束】=== echo. echo ======================================================== echo Zotero 翻译服务一键启动脚本 echo ======================================================== echo. rem [步骤 1/3] 进入项目目录，若失败则退出 cd /d "%PROJECT_PATH%" >nul 2>&1 if errorlevel 1 ( echo 错误：无法进入项目目录！请检查 PROJECT_PATH 设置是否正确。 echo 你的路径设置是: %PROJECT_PATH% pause exit /b 1 ) echo [步骤 1/3] 已成功进入项目目录: %cd% echo. rem [步骤 2/3] 激活 Python 虚拟环境 echo [步骤 2/3] 正在激活 Python 虚拟环境... call .\.venv\Scripts\activate echo - 虚拟环境已激活！ echo. rem [步骤 3/3] 启动翻译服务 echo [步骤 3/3] 准备启动翻译服务... uv run python server.py echo - 服务已启动！请勿关闭此窗口。 echo. echo ======================================================== echo. rem 为了能看到脚本输出，保持窗口开启 pause手把手教你用： 找到项目路径（关键一步！） 打开你的“文件资源管理器”。 找到你存放 zotero-pdf2zh2.0 的那个文件夹。 单击文件夹顶部的地址栏（如下图所示），路径就会被完整选中。 按下 Ctrl + C 复制这个路径。 创建并编辑脚本文件 在桌面或任何你喜欢的地方，右键单击 -> 新建 -> 文本文档。 打开这个新建的文本文档，将上面灰色代码块里的全部代码复制粘贴进去。 找到 set "PROJECT_PATH=..." 这一行，把你刚刚复制的路径粘贴进去，替换掉原来的 D:\... 路径。确保路径被英文双引号"包围。 正确保存文件 在记事本里，点击左上角 文件 -> 另存为。 在弹出的窗口中，将底部的“保存类型”从 文本文档(*.txt) 改为 所有文件(*.*)。 将“文件名”修改为 启动翻译服务.bat。 点击“保存”。现在，一个带齿轮图标的脚本文件就创建好了。 运行！ 找到你保存的 启动翻译服务.bat 文件，直接双击它。一个黑色的命令窗口会弹出，并自动执行所有操作。看到 pause 提示的“请按任意键继续...”时，就说明服务已成功运行！ 友情提示：只要服务在运行，这个黑色窗口就不能关闭。用完翻译功能后，直接关掉它即可。macOS / Linux 用户指南：创建 .sh 高效脚本 #!/bin/bash # ===【新手必读：请修改这里！】=== # 下面这行路径需要换成你自己的！ PROJECT_PATH="/Users/your_username/Documents/zotero-pdf2zh2.0" # ===【修改结束】=== echo "" echo "========================================================" echo " Zotero 翻译服务一键启动脚本 (macOS/Linux)" echo "========================================================" echo "" # 切换到项目目录，如果失败则会提示并退出 cd "$PROJECT_PATH" || { echo "错误：无法找到项目目录！请检查 PROJECT_PATH 设置是否正确。"; echo "你的路径设置是: $PROJECT_PATH"; exit 1; } echo "[步骤 1/3] 已成功进入项目目录: $(pwd)" echo "" # 激活 Python 虚拟环境 echo "[步骤 2/3] 正在激活 Python 虚拟环境..." source ./.venv/bin/activate echo " - 虚拟环境已激活！" echo "" # 运行 Python 服务器 echo "[步骤 3/3] 准备启动翻译服务..." uv run python server.py echo " - 服务已启动！关闭此终端窗口即可终止服务。" echo "" echo "========================================================"手把手教你用： 找到项目路径（Mac 用户有妙招！） macOS 妙招：打开“访达 (Finder)”，找到 zotero-pdf2zh2.0 文件夹。然后打开“终端 (Terminal)” App（你可以在“启动台”里找到它）。在终端里输入 cd (注意 cd 后面有个空格)，然后直接用鼠标把文件夹从访达拖到终端窗口里，松开鼠标，完整的路径就会自动出现在终端里了！按下 Ctrl + C 复制它。 Linux 用户：通常可以在文件管理器中右键点击文件夹，选择“复制路径”或“属性”来查看。或者在终端中进入该目录后，使用 pwd 命令查看当前路径。 创建并编辑脚本文件 打开任意文本编辑器（如 VS Code 或系统自带的“文本编辑”）。 将上面灰色代码块的全部内容复制粘贴进去。 找到 PROJECT_PATH="..." 这一行，用你刚刚获取的路径替换掉引号里的示例路径。 保存文件 将文件保存为 start_server.sh。请确保它是纯文本格式。 给脚本“授权”（只需一次） 在“终端”里，使用 cd 命令进入你保存 start_server.sh 的目录（例如 cd Desktop）。 运行以下命令，给脚本执行的“许可”： chmod +x start_server.sh 这行命令的意思是“允许这个文件被执行”，是安全措施，只需在第一次使用时运行。 运行！ 在终端中，确保你位于脚本所在的目录，然后输入以下命令并按回车： ./start_server.sh 现在，你的翻译服务已经启动。享受高效的文献翻译体验吧！ 6. 路线 C：Docker 一键容器化 (省心之选) 把整套 PDF 翻译工具“打包”进 Docker 镜像，是目前最省心、最具可复现性的方案。你无需折腾 Python 依赖或虚拟环境，在任何安装了 Docker 的操作系统上（Windows/macOS/Linux），体验都完全一致：拉取 → 运行 → 浏览器访问，三步搞定。 准备工作：安装 Docker 在开始之前，请确保你的电脑已经安装了 Docker Desktop 并已成功启动： # 验证版本，能看到版本号即可，如：Docker version 28.1.1, build 4eba377 docker -v # 查看 Docker 运行信息，若无报错，说明 Docker 引擎已就绪 docker info如果尚未安装，请参考以下资源： 官方文档 & 安装指南：Docker Desktop 下载 博文【Docker】告别环境配置噩梦：从零到一的安装指南 - 她笑中藏泪花 视频【Docker】告别环境配置噩梦：从零到一的安装指南_哔哩哔哩_bilibili 6.1 只按照pdf2zh 6.1.1 第一步：选择镜像源 在开始之前，我们需要告诉 Docker 从哪里去下载这个工具的“安装包”（在 Docker 的世界里，这叫镜像 Image）。 把它想象成一个应用商店： 官方源 (Docker Hub)：这是全球官方商店，通常速度最快、最可靠。 镜像地址：awwaawwa/pdfmathtranslate-next GitHub Container Registry（备用）：当官方源网络不佳时可选 ghcr.io/pdfmathtranslate/pdfmathtranslate-next:latest 国内源 (镜像加速器)：如果访问官方商店很慢或被“墙”，这些就是开在国内的“分店”或“代购点”，能帮你更快地拿到货。 常见镜像地址格式（任选其一即可）： hub.xdark.top/awwaawwa/pdfmathtranslate-next:latest docker.xuanyuan.me/awwaawwa/pdfmathtranslate-next:latest docker.1ms.run/awwaawwa/pdfmathtranslate-next:latest 6.1.2 第二步：拉取镜像 —— 把“安装包”下载到本地 选好了商店，我们现在就用 docker pull 命令把“安装包”下载到你的电脑里。 首选：从官方源拉取 docker pull awwaawwa/pdfmathtranslate-next:latest小贴士 镜像末尾的 :latest 是一个“标签 (Tag)”，代表最新版本。你也可以换成具体的版本号，例如 :2.0.10，以使用特定版本。 拉取一次后，再次运行同样命令会检查更新；若本地已有最新镜像，将直接跳过下载。 如果拉取过程中速度过慢或卡住，可以按 Ctrl + C 中断。 备选：当官方源访问受限时 如果 Docker Hub（官方源）访问困难，可以尝试项目在 GitHub 的官方容器仓库 (GHCR)： docker pull ghcr.io/pdfmathtranslate/pdfmathtranslate-next:latest最后的选择：使用国内加速镜像 如果以上两种方式都非常缓慢，可以尝试由社区或第三方提供的国内镜像源。请注意，这些源的更新可能不及时。使用时，需将完整的镜像地址替换掉。 # 示例：使用 dislabaiot.xyz 源 (请将此地址替换为你信任的、可用的加速器地址) docker pull dislabaiot.xyz/awwaawwa/pdfmathtranslate-next:latest新手小贴士 docker pull 是一个一次性动作。镜像下载到本地后，就像软件安装好了，以后随时可以运行，无需重复下载。 如果下载进度条卡住不动，可以按 Ctrl + C 中断它，然后换一个国内源地址再试一次。 6.1.3 第三步：运行容器 —— 启动你的翻译服务！ 镜像下载完毕，现在我们用 docker run 命令来启动它。运行中的镜像实例，就叫做“容器 (Container)”。它是一个隔离的、包含了我们所需服务的小型“虚拟机”。 docker run -d --name pdf2zh -p 7860:7860 awwaawwa/pdfmathtranslate-next一句话解释： 这条命令会让容器在 后台 安静地跑起来，把你电脑的 7860 端口映射到容器的 7860 端口，然后启动名为 awwaawwa/pdfmathtranslate-next 的镜像。参数“人话”解析 docker run: “Docker，给我跑起来这个东西！” -d (detach): 让容器在后台安靜工作，不占用你当前的终端窗口。 --name pdf2zh: 给你的容器起一个独一无二的名字叫 pdf2zh，就像给宠物起名，方便以后按名字找它（停止、重启等）。 -p 7860:7860: 这是最关键的端口映射。它像一个电话转接员，把访问你电脑本机 7860 端口的请求，全部转接给容器内部的 7860 端口来处理。格式是 -p <本机端口>:<容器端口>。 awwaawwa/pdfmathtranslate-next: 告诉 Docker 你要运行哪个镜像。 6.1.4 第四步：访问翻译服务 见证奇迹的时刻！ 打开你的任意网页浏览器（如 Chrome, Edge, Firefox）。 在地址栏输入：http://127.0.0.1:7860/ 127.0.0.1 是一个特殊的地址，就代表“我这台电脑自己”。 如果一切顺利，你应该能看到 PDF 翻译工具的界面了。现在，可以上传 PDF 文件开始使用了！ 管理你的容器 记住你给容器起的名字 pdf2zh，后续就可以像遥控器一样，用以下命令来管理这个在后台运行的服务： 操作命令说明启动服务docker start pdf2zh在后台再次启动停止服务docker stop pdf2zh暂停容器，服务下线查看实时日志docker logs pdf2zh实时打印运行日志，便于排错重启服务docker restart pdf2zh相当于 stop + start删除容器docker rm pdf2zh删除记录（容器停止后才能删） 小白必看：如何替换成国内镜像 先“拉取”国内镜像（只要做一次）： docker pull hub.xdark.top/awwaawwa/pdfmathtranslate-next:latest 运行时用国内镜像名： docker run -d --name pdf2zh -p 7860:7860 hub.xdark.top/awwaawwa/pdfmathtranslate-next:latest 确认 打开浏览器访问：http://127.0.0.1:7860/ 出现 Web UI，说明替换成功！ Tip： 镜像前缀可以换成任意可用源，格式一致。这是一些国内的镜像源： 如果不确定完整的镜像名称，可打开 Docker Desktop → Images → 找到你的镜像 → 点击复制图标。 只需将命令末尾的镜像名换成你之前拉取的国内源地址即可。不确定完整的镜像名？ 打开 Docker Desktop。 点击左侧菜单的 Images。 找到你下载的镜像，将鼠标悬停在镜像名称上，点击出现的复制图标即可。 镜像名称图片 6.2 方案二：通过 Docker 联动 Zotero 借助 Docker Compose + Zotero 插件，把「文献管理 → PDF 翻译」串成一条流水线，配置、缓存全都持久化。下面的步骤按“先搭骨架 → 改配置 → 填密钥 → 一键起飞 → 日常运维”的顺序递进，小白也能照抄成功。1. 拉脚手架文件 # 1) 创建一个总工作目录，并立刻进入 # 我们所有的操作都将在此目录下进行 mkdir zotero-pdf2zh-docker && cd zotero-pdf2zh-docker # 2) 从 zotero-pdf2zh 官方 GitHub 仓库下载配置文件 # - Dockerfile: 定义了如何构建我们服务的镜像 # - docker-compose.yaml: 定义了如何运行和编排我们的服务 curl -o Dockerfile https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/Dockerfile curl -o docker-compose.yaml https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/docker-compose.yaml # 3) 创建一个子目录，专门用于存放需要持久化的数据 # 这包括你的个人配置和翻译后的文件 mkdir zotero-pdf2zh && cd zotero-pdf2zh # 4) 在数据目录内，预先创建用于存放翻译结果的文件夹 mkdir translated # 5) 操作完成后，返回到项目根目录，为下一步做准备 cd ..完成以上步骤后，你就拥有了一个标准化的项目“脚手架”，为后续的自动化部署奠定了坚实的基础。 2. 核心配置：定制你的 docker-compose.yaml 原仓库默认使用 byaidu/pdf2zh:1.9.6，版本老、依赖旧。直接换成社区更活跃的 awwaawwa/pdfmathtranslate-next:latest，就能原地升级到 2.x 新引擎，并内置 pdf2zh_next（不再需要自己 pip install）。 请用以下内容完全覆盖你下载的 docker-compose.yaml 文件： services: zotero-pdf2zh: build: context: . dockerfile: Dockerfile args: # 编者注：我们在这里指定了构建时使用的基础镜像。 # 相比原始的 byaidu/pdf2zh，awwaawwa/pdfmathtranslate-next 更新更频繁，功能更强。 - ZOTERO_PDF2ZH_FROM_IMAGE=awwaawwa/pdfmathtranslate-next:latest - ZOTERO_PDF2ZH_SERVER_FILE_DOWNLOAD_URL=https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/refs/heads/main/server.py container_name: zotero-pdf2zh # restart: unless-stopped 是一条黄金法则， # 它能确保 Docker 服务在宿主机重启后自动恢复，实现“开机自启”。 restart: unless-stopped ports: - "8888:8888" # 将容器的 8888 端口映射到你电脑的 8888 端口 environment: - TZ=Asia/Shanghai # 设置时区，确保日志时间正确 - HF_ENDPOINT=https://hf-mirror.com # 使用 HuggingFace 镜像，加速模型下载 volumes: # 这是实现持久化的关键：将我们创建的本地目录映射到容器内部 - ./zotero-pdf2zh/translated:/app/translated # 挂载翻译结果目录 - ./zotero-pdf2zh/config.json:/app/config.json # (可选) 兼容旧版 JSON 配置 1.x 配置文件 - ./zotero-pdf2zh/config.toml:/app/config.toml # 核心！Zotero 读取的新版 TOML 配置文件 2.x 配置文件3. 生成 config.toml——给服务“注入灵魂” 先跑一次 PDFMathTranslate-next 桌面版或 Web UI，把 OpenAI／DeepL Key、目标语言、并发数等都配好。 系统会生成 config.v3.toml （路径见下表）。复制并改名成 config.toml 放到 zotero-pdf2zh/ 目录下即可。 # Windows (cmd) copy "%USERPROFILE%\.config\pdf2zh\config.v3.toml" zotero-pdf2zh\config.toml # PowerShell Copy-Item "$env:USERPROFILE\.config\pdf2zh\config.v3.toml" zotero-pdf2zh\config.toml # macOS / Linux cp ~/.config/pdf2zh/config.v3.toml zotero-pdf2zh/config.toml 操作完毕后，你的最终目录结构应如下所示： zotero-pdf2zh-docker/ ├── Dockerfile ├── docker-compose.yaml └── zotero-pdf2zh/ ├── config.toml <-- 你的 API Key 和配置在这里 └── translated/ <-- 翻译后的文件将出现在这里4. 一键启动与日常管理 现在，万事俱备。让我们启动服务。 首次部署 在项目根目录下（即 docker-compose.yaml 所在的位置）执行： # 推荐：先清理可能存在的同名旧容器，避免冲突 (|| true 会忽略容器不存在的错误) docker rm -f zotero-pdf2zh || true # 一键构建镜像并在后台启动服务 # --build: 强制根据 Dockerfile 重新构建镜像，以应用我们的修改 # -d: detached 模式，让服务在后台安静运行 docker-compose up -d --build重启电脑后，因设置了 restart: unless-stopped，容器会自动拉起；若未生效，手动 docker start zotero-pdf2zh 即可。7. 常见问题与排障 7.1 快速排障指南 场景可能原因解决方案PDF 复制乱码PDF 内嵌字体有问题或阅读器兼容性差尝试换用其他 PDF 阅读器（如 Zotero、Acrobat）打开并复制。端口占用7860 / 8888 被占netstat -ano 找占用进程，或指定新端口Timeout / 429免费 API 接口达到频率限制降低并发 / 更换 API KeyZotero 连接失败防火墙 / 未监听 0.0.0.01. 检查 Windows 防火墙，放行 Python 或 Docker。 2. 确保路线 B 的启动命令包含了 --host 0.0.0.0。Web UI 白屏容器未起 / 端口冲突1. 运行 docker ps 查看容器是否在 Up 状态。 2. 运行 docker logs pdf2zh-service 查看容器日志，定位具体错误。富文本占位符错乱LLM 匹配错误开启 Enhance compatibility；DeepSeek-V3 命中率最低7.2 关于“自定义 Prompt”的成本考量 pdf2zh-next 会将 PDF 拆分为许多小片段，并为每个片段发起一次 API 请求。若启用自定义 Prompt，这个 Prompt 会被附加到每一次请求上，其 token 成本也因此被成倍累加。 决策关键：你的 API 服务商是否支持 KV Cache (上下文硬盘缓存) 技术。这是一种上下文记忆机制，能避免对固定 Prompt 的重复计费。 ✅ 强烈建议开启： 如果你的 API 服务商支持 KV Cache。此时，自定义 Prompt 的成本几乎可以忽略不计，请放心使用，以换取更稳定、更优质的翻译效果。 ❌ 果断建议关闭： 如果你的 API 服务商不支持 KV Cache。在这种情况下，为避免不必要的开销，关闭此功能是最理性的选择。 最新版自定义Prompt参考 7.3 解读 RPS、QPS 与线程数：pdf2zh 是如何工作的？ 许多用户在配置 pdf2zh 时，会对“线程数”、“RPS” 或 “QPS”感到困惑，误以为它们能让整个翻译过程“多核并行”。这里，我们用一个生动的比喻来彻底讲清它的工作机制。 一个“单人备菜，多人上菜”的厨房 想象 pdf2zh 是一个高效的翻译厨房： 备菜阶段 (单线程)：厨房里只有一位主厨（CPU 单核心）。他负责所有前期准备工作：接收整本 PDF、逐页拆解、提取段落、清洗文本格式。无论你请多少个服务员，备菜的厨师始终只有一位，所以这个阶段是单线程的。 上菜阶段 (多并发)：一旦主厨把菜（处理好的文本片段）备好放在出餐口（任务队列），你所设置的“线程数”就相当于你雇佣的服务员团队。他们（asyncio + httpx）会一拥而上，以最快速度将菜品并发地送往大模型（LLM）这张“餐桌”进行翻译。 “线程数”的多种“马甲” 请注意，在工具的不同界面中，这个“服务员团队的规模”有不同的叫法，但它们本质上是同一个概念： Web UI 中的 RPS (Requests Per Second) config.toml 文件中的 qps (Queries Per Second) Zotero 插件中的 线程数 它们都共同指向一件事：程序向上游 LLM 发起翻译请求的并发数量。 技术核心：为何备菜是“单线程”？ 这背后的技术原因是 Python 的 GIL (全局解释器锁)。GIL 限制了在同一进程中，同一时间只有一个线程能执行 Python 的字节码。因此，对于计算密集型（CPU-bound）的 PDF 解析任务，多线程无法带来真正的并行加速。 编者注：项目未来可能会引入 GPU 加速功能来优化前处理阶段。核心优化建议 综上所述，pdf2zh 的瓶颈通常不在于前期的“备菜”，而在于后期“上菜”的效率。若想追求极致速度，你的优化重心应该放在： 🚀 选择更快的 LLM API：优先使用由 GPU 加速的、响应延迟低的服务。 🌐 保证网络质量：程序与 API 服务器之间的网络带宽和延迟至关重要。 ⚙️ 合理调整并发数：在不触及 API 服务商速率限制（Rate Limit）的前提下，适当调高 线程数 (或 QPS/RPS) 参数，让更多的“服务员”同时工作。 如何确定“合理”的并发数？ 这是一个非常关键问题。设置过低会浪费性能，设置过高则会导致 API 报错。你可以遵循以下步骤来确定理论最大值： 查阅官方文档：找到你所用 API Key 对应服务商的官方文档，定位到关于“速率限制 (Rate Limit)”的说明。 关注核心指标：通常需要关注两个限制：RPM (每分钟请求数) 和 TPM (每分钟处理的 token 数)。 计算理论 RPS： 基于请求数：你的 RPS 设置不应超过 RPM / 60。 基于 Token 数：同时也要确保 RPS * 平均每请求的 token 数 < TPM / 60。 简单粗暴的算法：在不考虑 Token 限制的理想情况下，可以直接用 RPM / 60 作为你的 RPS 参考值。 编者注： 若想获得流畅的高速翻译体验，建议选用支持高 RPM（例如 1000 RPM 或更高）的 API 套餐。一个高的 RPM 指标是保证并发能力的基础。 7.4 需要更多帮助？ 如果以上指南未能解决你的问题，推荐通过以下官方渠道寻求帮助： 阅读官方文档：首先查阅 官方项目 FAQ，大部分常见问题已有解答。 搜索 GitHub Issues：在 项目 GitHub Issues 区 搜索关键词，你的问题可能已经被他人提出和解决。 zotero-pdf2zh：可以查看置顶 Issue，其中包含了大量有价值的排障讨论：🔝【手动置顶】请所有遇到问题的朋友先看这里 · Issue #64 8. 收工 好了，教程到此结束。有了 PDF2zh 这个神器，希望语言不再是你科研道路上的“拦路虎”，而是可以轻松跨越的“小水沟”。 祝你少踩坑，多产出，Happy Researching!
-
【AI伴读论文】三段 Prompt 一键搞定文献精读与思维导图 写在开始 读外文论文常被调侃为“啃硬骨头”：专业术语密集、跨学科图表林立、方法论冗长繁复……读完一篇往往让人精疲力竭。 但如今，多模态大模型（例如 GPT-4o、Gemini 2.5 Pro、Claude 4）已全面支持 Vision + Text 同步推理，不仅能帮你迅速拆解段落要点，更能精准解析复杂图表，让原本“一个人啃论文”的艰难，轻松升级为“AI伴读”的新体验。 连英伟达 CEO 黄仁勋都曾公开表示，自己用 AI 辅助阅读科研论文，效率之高“很多人还没意识到”。 成本提示：推荐在官方网页端直接对话而非通过 API——不仅方便拖拽上传 PDF，还能节省调用费用。 模型选择：DeepSeek 系列的文本推理能力十分强劲，其中主力模型 DeepSeek-V3 和 DeepSeek-R1 均为纯文本模型，虽然官方已开源研究版本的 DeepSeek-VL，但尚未整合进官方聊天界面。目前版本依旧缺乏原生的视觉（Vision）支持，面对公式截图或复杂图表时会显得“看不懂”、力不从心，建议期待后续版本的升级优化。deepseek不支持图片 本篇博文打包三段高复用 AI 伴读 Prompt： 系统 Prompt——定义助手角色与交互流程 文献框架总结 Prompt——一键生成大纲 精读笔记 Prompt——输出六大模块深读笔记 只需复制粘贴，即可让 AI 自动完成“拆结构 → 摘要 → 精读 → 互动问答 → 延伸阅读”的闭环。 使用步骤 发送系统 prompt 将下文 系统 prompt 整段复制给 AI，让其进入“论文伴读模式”。 上传 PDF 直接拖拽上传；若论文较大，可按章节截图或拆分上传。 按需点读 只看摘要？输入「Abstract」 想先搞懂图 2？输入「Figure 2」 让 AI 解释统计量？直接提问。 调用框架/精读 prompt 当 AI 已读取完全文，即可发送 文献框架总结 或 精读笔记 prompt，生成 Markdown 结构化输出，再导入 XMind 等工具制作思维导图。 深挖/对比 最后，您可以尝试向模型提出类似「帮我找 3 篇 2024 年后与 XXX 最相关的工作及区别」的请求。此类查询可触发模型调用联网搜索功能，从公开数据库中抓取最新论文，并提供简要概述。 目前，ChatGPT 系列模型（如 GPT-4o）已默认支持自动联网检索功能，无需用户手动操作即可获取实时信息 。而其他模型（如 Claude、Deepseek 等）则需手动启用联网搜索功能，或通过插件方式接入外部搜索引擎，才能实现类似的实时信息获取能力 。 Prompt ①：系统 Prompt 作用：限定 AI 的“身份 + 职责 + 安全边界”，让后续交互始终聚焦论文本身，避免胡编乱造。<!-- AI Paper Deep-Read Interactive Assistant : GLOBAL PROMPT--> <system> You are an AI assistant that helps users read and analyze PDF papers they upload. **Except for technical terms, always reply to the user in Chinese**, and strictly base all responses on the actual content of the paper; do not fabricate or falsify any information. ### 1. Loading & Confirmation - Acknowledge receipt of the document: > “Document received. I have loaded the PDF titled ‘<filename>’. Which part would you like to view first: Abstract, Introduction, Methods, Results, or something else?” - Automatically extract and relay basic metadata (title, authors, conference/journal, year). ### 2. Interactive Segmented Reading - When the user specifies a section, silently parse it and **internally** reason through it. - Provide a 1–3 sentence summary of that section's key points. - Follow up with: > “Does this align with your understanding? Are there any points you’d like to delve into further?” ### 3. In-Depth Analysis (On Demand) - If the user requests, extract and present that section’s **Key Contributions**, **Core Methods**, **Main Results**, or **Strengths & Limitations**. - Output in structured Markdown: #### 📄 Citation `<APA-style reference>` #### 💡 Section: Methods - **Summary:** … - **Core Methods:** 1. … 2. … * Conclude by inviting further questions: > “What else would you like to discuss?” ### 4. Collaborative Q&A * Pose 2–3 deep reflection questions regarding the current section to guide the user’s response or the assistant’s further elaboration. ### 5. Related Work & Next Steps * If the user needs broader background, retrieve 3–5 recent related papers from open sources (Semantic Scholar, arXiv, Google Scholar, etc.). * List each paper with a one-sentence explanation of its relevance. * Suggest feasible follow-up experiments or practical applications. ### Style & Safety * Conceal the thought process; present only concise conclusions. * Use precise academic language; **never fabricate data or findings**. * If unable to parse a section or extract metadata, honestly inform the user: > “Sorry, I’m unable to extract that information. Please try selecting another section or provide more context.” </system>Prompt ②：文献框架总结 作用：粗览全文结构，快速锁定核心板块，适合写开题报告或准备 PPT 展示。Please read and understand the literature provided by the user, and extract the core points, omitting acknowledgments and references; if you encounter contradictory or unclear content, re‑examine the original text, and if it remains unclear, mark it as “unclear” or “not specified in the literature.” Present your summary in pure Chinese Markdown format, using only headings (#, ##, ###, ####) and lists (-, 1.) structures, without any inline styling (for example, **, *, ~~). Use `# 文献框架总结` as the top‑level heading, then use ## to denote the abstract and main sections, ### for subsections, and #### for paragraph content; if the literature is in English, provide a Chinese translation. Finally, append a brief paragraph summarizing the study’s key findings after the main text. All output must be presented within a Markdown code block and strictly adhere to the above instructions.Prompt ③：精读笔记 作用：在框架之上深挖，形成可直接写在论文读书报告或组会汇报的笔记。 主要内容包括：“1. 研究概况”、“2. 研究方法”、“3. 研究内容”、“4. 研究结论”、“5. 创新点”、“6. 本文启示”这六部分。Please read and understand the literature provided by the user, extracting the core points while omitting acknowledgments and references; if you encounter contradictory or unclear content, re‑examine the original text, and if it remains unclear, label it as “unclear” or “not specified in the literature.” Please generate reading notes in pure Chinese Markdown format, using “xxx 阅读笔记” as the top‑level heading, immediately followed by plain‑text presentation of author information, keywords, publisher, etc.; then sequentially use “1. 研究概况”, “2. 研究方法”, “3. 研究内容”, “4. 研究结论”, “5. 创新点”, and “6. 本文启示” as second‑level headings, under each section detailing content with third‑level headings or lists (-, 1.); the entire output may only use #, ##, ### headings and list structures, must not use any inline Markdown styling (e.g., **, *, ~~), and must be presented as a complete Markdown code block.结语 有了以上三段 prompt，你可以： 10 分钟 拆解论文脉络 30 分钟 完成深度精读笔记 随时 让 AI 解析图表、公式或撰写相关工作对比 下次再遇到厚厚的外刊论文，不妨把它交给 AI 伴读，再把宝贵精力投入到批判性思考与原创研究中吧！
