fireplay-translation

可复用的 Python 翻译路由包，支持同步和原生异步调用。调用方只依赖路由接口；默认实现以 qwen-mt-flash 为主模型，仅在主模型返回 429/RPM 限流时使用 qwen3.8-flash，并短暂熔断主模型，避免限流期间反复发送必然失败的请求。

安装与使用

从公司包仓安装构建后的 wheel，或在源码仓内执行：

uv build
pip install fireplay-translation

import os

from fireplay_translation import QwenConfig, create_qwen_translator

translator = create_qwen_translator(
    QwenConfig(
        api_key=os.environ["DASHSCOPE_API_KEY"],
        # 推荐换成与 API Key 同地域的 Model Studio 工作空间地址。
        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 等）使用原生 httpx.AsyncClient，不会阻塞事件循环：

import os

from fireplay_translation import QwenConfig, create_async_qwen_translator


async def main() -> None:
    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",
        )
        print(result.text)

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

路由语义

• qwen-mt-flash 正常、超时、鉴权错误或服务异常时，错误原样返回，不静默换模型。
• 只有 429 限流会触发 qwen3.8-flash，因此调用方能区分容量问题和配置/服务故障。
• 收到 429 后按 max(Retry-After, rate_limit_cooldown_seconds) 暂停主路由，默认 60 秒。
• Qwen3.8 回退请求关闭 thinking，并要求只返回译文。
• TranslationResult.fallback_used、model 和 token 字段可用于监控成本与回退率。

扩展其他模型或厂商

同步后端实现 TranslationBackend，异步后端实现 AsyncTranslationBackend；分别注入 Translator 或 AsyncTranslator 即可，业务项目无需了解供应商协议：

from fireplay_translation import Translator

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

异步扩展的 translate(TranslationRequest) 方法定义为 async def，路由调用方式为 await translator.translate(...)。

发布前建议依次执行：

uv run pytest
uv build

发布到公司包仓后，业务项目按普通版本依赖安装：

uv add fireplay-translation