fireplay-translation

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

安装与使用

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

uv build
pip install dist/fireplay_translation-0.1.0-py3-none-any.whl

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)

路由语义

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

扩展其他模型或厂商

实现一个带 model 属性和 translate(TranslationRequest) 方法的 TranslationBackend，再注入 Translator 即可；业务项目无需了解供应商协议：

from fireplay_translation import Translator

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

发布前建议依次执行：

uv run pytest
uv build

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

uv add fireplay-translation