fireplay-translation

可复用、可扩展的 Python 翻译路由包，支持同步和原生异步调用。

默认路由使用 qwen-mt-flash；只有主模型返回 HTTP 429/RPM 限流时才切换到 qwen3.8-flash。收到限流后会短暂熔断主模型，避免在限流窗口内重复发送必然失败的请求。鉴权、超时和普通服务错误不会被备用模型隐藏。

安装

从公共 PyPI 安装：

pip install fireplay-translation

使用 uv：

uv add fireplay-translation

包要求 Python 3.10 或更高版本。

同步调用

import os

from fireplay_translation import QwenConfig, create_qwen_translator

translator = create_qwen_translator(
    QwenConfig(
        api_key=os.environ["DASHSCOPE_API_KEY"],
        # 按 API Key 所在地域覆盖此地址。
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    )
)

result = translator.translate(
    "Hello, world",
    source_language="auto",
    target_language="zh-CN",
)

print(result.text)
print(result.model, result.fallback_used)

异步调用

FastAPI、Starlette、aiohttp 等异步服务应复用原生异步客户端，避免阻塞事件循环：

import os

from fireplay_translation import QwenConfig, create_async_qwen_translator


async def translate_once() -> str:
    async with create_async_qwen_translator(
        QwenConfig(api_key=os.environ["DASHSCOPE_API_KEY"])
    ) as translator:
        result = await translator.translate(
            "Hello, world",
            source_language="auto",
            target_language="zh-CN",
        )
        return result.text

长生命周期服务应在启动时创建一个 translator，在关闭时调用 await translator.aclose()，从而复用并正确释放连接池。

路由语义

• qwen-mt-flash 成功时直接返回结果。
• 只有 HTTP 429 会触发 qwen3.8-flash。
• 限流熔断时间为 max(Retry-After, rate_limit_cooldown_seconds)，默认至少 60 秒。
• 主模型的非 429 错误原样返回。
• 主模型限流且备用模型失败时，TranslationFallbackError 保留两次异常。
• TranslationResult 暴露实际模型、是否兜底、兜底原因和上游 token 用量。

完整契约见 Python 公共 API 和 429 兜底决策。

扩展其他模型或供应商

同步后端实现 TranslationBackend，异步后端实现 AsyncTranslationBackend，再注入 Translator 或 AsyncTranslator：

from fireplay_translation import Translator

translator = Translator(
    MyPrimaryBackend(...),
    rate_limit_fallback=MyFallbackBackend(...),
)

架构和资源生命周期约定见 翻译路由架构。

开发

uv sync --frozen
uv run pytest
uv build

发布新版本前必须遵循 公共 PyPI 发布手册，不要从包含旧版本制品的 dist/ 目录直接批量上传。

文档

项目知识索引 是文档入口和权威地图。项目文档使用稳定 ID、生命周期状态和生成式清单管理。先把 PROJECT_DOC_STEWARD_SKILL 指向本机安装的 project-doc-steward 目录，再执行：

uv run "$PROJECT_DOC_STEWARD_SKILL/scripts/inventory_documents.py" . --sync-ai-policy
uv run "$PROJECT_DOC_STEWARD_SKILL/scripts/validate_metadata.py" . --check

分发与许可

• PyPI：fireplay-translation
• 许可证元数据：Proprietary

在项目所有者明确授权前，不要假定公共 PyPI 分发等同于开放源码许可。