ComfyUI 关键词翻译文本插件开发指南：从零实现多语言支持-平芜编程栈

ComfyUI 关键词翻译文本插件开发指南：从零实现多语言支持

1. 背景：为什么非得自己写翻译插件？

ComfyUI 的节点名、提示词、下拉选项全是英文，对国内刚上手的同学来说，每次都得开着翻译网页来回切换。
官方仓库里虽然零星有人提 PR，但要么只汉化界面，要么把词条写死在代码里，升级一覆盖就全没；第三方脚本又只能批量替换 JSON，做不到“随用随译”。更别提工作流里动态生成的关键词——现成的方案根本够不着。
于是干脆自己撸一个插件：节点标签、提示模板、甚至运行时拼出来的字符串，都能实时翻译成目标语言，还要能缓存、能离线、能换引擎。下面把踩坑过程完整记下来，给第一次写 ComfyUI 扩展的小伙伴一个“能跑又能改”的样板。

2. 架构设计：让 ComfyUI 把你“当自己”

ComfyUI 的插件机制说简单也简单：只要在custom_nodes目录下放一个文件夹，里面包含__init__.py，启动时会自动import并执行NODE_CLASS_MAPPINGS注册表。
我们要做的是：

注册一个“翻译节点”，接收文本输入，输出翻译结果。
在插件被加载时，向 ComfyUI 的“应用生命周期”挂钩子：
- init阶段初始化缓存、读取配置。
- prompt 开始执行阶段把用户填的 API Key 注入到节点上下文。
- prompt 结束阶段把缓存落盘，防止下次启动再翻一遍。

事件驱动模型用到了 ComfyUI 内置的server.PromptServer.instance回调，伪代码如下：

from server import PromptServer def on_prompt_start(json_data): TranslatorHub.set_api_key(json_data.get("translate_api_key")) PromptServer.instance.add_on_prompt_handler(on_prompt_start)

这样做的好处：

不侵入 ComfyUI 核心，升级无感。
节点、缓存、配置三者解耦，后续换翻译引擎只改 Hub 里一行代码。

3. 核心实现：能跑、能缓存、还能异步

3.1 翻译服务 API 调用封装

下面给出一个最小可运行的 Google Translate 免费层封装，带类型注解、超时、重试、异常兜底：

import httpx from typing import Optional class GoogleTranslator: def __init__(self, api_key: str, timeout: int = 10): self.key = api_key self.client = httpx.AsyncClient(timeout=timeout) async def translate(self, text: str, target_lang: str = "zh-CN") -> Optional[str]: url = "https://translation.googleapis.com/language/translate/v2" params = { "q": text, "target": target_lang, "key": self.key, "format": "text" } try: resp = await self.client.get(url, params=params) resp.raise_for_status() return resp.json()["data"]["translations"][0]["translatedText"] except Exception as e: print(f"[Translate] {e}") return None

3.2 本地 LRU 缓存

翻译是按字符计费的，同一个“masterpiece, best quality”提示词在一天内能被不同的工作流调用几十次，不缓存就是烧钱。
用functools.lru_cache太简单，我们还需要持久化到磁盘，于是自己包一层：

import pickle, json, os, time from collections import OrderedDict from pathlib import Path class LRUFileCache: def __init__(self, cache_dir: str, max_mem: int = 512): self.cache_dir = Path(cache_dir) self.cache_dir.mkdir(exist_ok=True) self._mem_cache: OrderedDict[str, tuple] = OrderedDict() self.max_mem = max_mem def _make_key(self, text: str, lang: str) -> str: return f"{hash(text)}_{lang}" def get(self, text: str, lang: str) -> Optional[str]: key = self._make_key(text, lang) # 内存命中 if key in self._mem_cache: self._mem_cache.move_to_end(key) return self._mem_cache[key][0] # 磁盘命中 file = self.cache_dir / f"{key}.pkl" if file.exists(): with file.open("rb") as f: trans, ts = pickle.load(f) # 缓存 30 天 if time.time() - ts < 30 * 86400: self._mem_cache[key] = (trans, ts) self._trim() return trans else: file.unlink() return None def set(self, text: str, lang: str, trans: str): key = self._make_key(text, lang) ts = time.time() self._mem_cache[key] = (trans, ts) file = self.cache_dir / f"{key}.pkl" with file.open("wb") as f: pickle.dump((trans, ts), f) self._trim() def _trim(self): while len(self._mem_cache) > self.max_mem: self._mem_cache.popitem(last=False)

3.3 异步处理优化

ComfyUI 默认在同一线程里跑节点，如果翻译节点阻塞，整个工作流都会卡。把翻译逻辑放到asyncio池子里，节点里只拿结果：

import asyncio async def map_translate(texts: list[str], lang: str) -> list[str]: tasks = [translator.translate(t, lang) for t in texts] return await asyncio.gather(*tasks)

节点内部用execute()里的loop.run_until_complete()把异步桥接回来，保证 ComfyUI 不报错。

4. 性能考量：少花钱、多办事

请求频率限制
Google 免费层默认 100 次/秒，超过就 429。Hub 里加令牌桶asyncio.Semaphore(5)，并发不超过 5 条，同时给节点暴露一个“QPS”滑条，用户自己压测。

失败重试策略
网络抖动常见，用tenacity库三行代码搞定指数退避：

from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=10)) async def translate_with_retry(...):

离线模式支持
检测到 API Key 为空时，自动降级到本地词典（JSON 文件），并给出黄色警告。用户跑测试工作流不再烧额度。

5. 避坑指南：前人踩过的坑，你不用再踩

常见 API 调用限制
免费额度是按“字符”不是按“请求”，一个 200 字的提示词就算一次，别傻乎乎地循环 200 次单行请求。把整段文本先合并，翻译完再按行拆分。
内存泄漏预防
httpx.AsyncClient一定做成单例，节点里不要每调用一次就new一个。推荐用aiohttp同理，否则 GPU 还没爆，内存先被连接池吃光。
多语言资源文件管理
采用“一个模块一个 YAML”的方式，例如zh-CN/ui.yml、ja-JP/ui.yml，键名用英文原词，Git 合并冲突一眼能看出来。
加载时把 YAML 转成types.MappingProxyType只读映射，运行期改不了，防止节点被意外篡改。

6. 扩展建议：把插件做成“翻译超市”

支持更多翻译引擎
把TranslatorHub做成策略模式，Google、DeepL、腾讯、Azure 都实现同一接口，用户下拉框里随便切。
自定义词典
允许用户放user_dict.csv，格式“英文,中文”，插件启动时读进内存，翻译前先做全文替换，专业术语不再被机翻带歪。
增量更新
把缓存目录做成 Git 子模块，团队内共享，同一份命中文件大家用，新人第一天就享受“秒翻”。

7. 测试用例 & 思考题

打开 ComfyUI，拖入“翻译节点”，输入“a cute cat wearing a top hat”，目标语言选“zh-CN”，点击运行，确认输出“一只戴着高帽子的可爱猫咪”。
断开外网，清空 API Key，再次运行同一条提示，观察是否降级到本地词典并出现警告横幅。
把 QPS 调到 20，观察日志是否出现 429，重试后是否能最终成功。

留给读者的小作业