TrnRT 社区与支持完整指南:如何申请新模型、报告漏洞并跟进发布流程
TrnRT 社区与支持完整指南:如何申请新模型、报告漏洞并跟进发布流程
TrnRT 是 RunAnywhere 开源的 LLM 推理引擎,面向 AWS Trainium(trn2.48xlarge),以 NKI megakernels 驱动 decode、支持 1M token 上下文,并提供 OpenAI 兼容 API。本文带你完整走通 TrnRT 社区与支持 的三大流程:如何申请支持新模型、如何正确报告漏洞、以及如何跟进项目发布流程,新手也能照着做。
📍 先认识 TrnRT:它为你解决了什么
在参与社区前,先了解项目现状有助于写得更准确的 issue:
| 维度 | 现状 |
|---|---|
| 硬件 | AWS Trainium2(trn2.48xlarge,16 芯片、96 GiB HBM 每片),✅ 已支持 |
| 模型 | GLM-5.3-Flash(320B MoE、18B 激活、FP8、1M token 上下文),✅ 已支持 |
| 更多开源模型 | 🔜 陆续支持中,可提交模型申请 |
| API | Chat / completions、流式、工具调用、推理输出(OpenAI 兼容) |
| 许可证 | Apache 2.0 |
完整文档入口在 docs/README.md,涵盖部署(docs/DEPLOY.md)、API(docs/API.md)、配置(docs/CONFIGURATION.md)等。
🧭 遇到问题先查哪里:官方支持渠道一览
SUPPORT.md 提供了一张"你想做什么 → 去哪里"的速查表,这是所有社区入口的总目录:
| 你想做的事 | 去哪里 |
|---|---|
| 部署 TrnRT 或修复启动检查 | docs/DEPLOY.md,然后 docs/KNOWN_ISSUES.md |
| 获取 Trainium2 实例 | docs/AWS.md |
| 查某个 flag 或环境变量 | docs/CONFIGURATION.md |
| 调用 API | docs/API.md |
| 提问讨论 | 项目 Discussions |
| 报告 Bug 或回归 | 项目的 issue(模板见下文) |
| 报告安全问题 | SECURITY.md,绝不用公开 issue |
| 自有算力运行 / 支持新模型 | 邮件 founders@runanywhere.ai |
💡 新手建议:90% 的问题(启动检查失败、flag 用法、API 字段)先查上表对应的文档,查不到再提 issue,能显著加快响应速度。
🚀 如何申请支持新模型(Model Request 完整步骤)
TrnRT 当前首个支持的模型是 GLM-5.3-Flash,但引擎、路由、缓存与编译流水线都是为承载更多模型家族而设计的。想申请支持一个新模型,按下面 3 步走。
第 1 步:整理你的模型与负载信息
打开项目仓库的 issue 页面,选择 Model request 模板(源码见 .github/ISSUE_TEMPLATE/30-model-request.yml),它会要求你填三个字段:
| 字段 | 说明 |
|---|---|
| Model | Hugging Face 仓库 id 和 revision,如 org/model @ <commit>(必填) |
| Target instance | 目标实例,如 trn2.48xlarge |
| Workload | 你需要的上下文长度、并发数和延迟目标 |
第 2 步:说明"为什么"比"是什么"更重要
在 Workload 里写清业务场景:上下文长度(如 128K / 1M)、并发 agent 数、首 token 与端到端延迟目标。这样维护者才能判断该模型是否适配现有的 NKI megakernels 与离线编译流水线。
第 3 步:了解一个新模型家族需要什么
如果你是开发者,想直接动手支持新模型,先读 docs/ARCHITECTURE.md 的 "Adding a model family" 章节,并先开一个 issue 与维护者对齐方案——这是 CONTRIBUTING.md 的明确要求:较大的改动(新模型家族、新 kernel、API 变更)要先开 issue 讨论,再动手写代码。
🏢 如果你希望在自有算力上运行 TrnRT,或企业级地推进新模型支持,可以直接邮件 founders@runanywhere.ai(见 SUPPORT.md)。
🐛 如何报告 Bug 与性能回退
项目关闭了空白 issue(.github/ISSUE_TEMPLATE/config.yml 中 blank_issues_enabled: false),所有报告都走结构化模板,这对双方都是好事:字段齐全,修复更快。
Bug 报告要写清的 6 个字段
Bug 模板(源码见 .github/ISSUE_TEMPLATE/10-bug-report.yml)要求:
- What happened, and what you expected:发生了什么、你期望什么(必填)
- Exact command and request:完整的
trnrt .../docker run ...命令,API 类问题还要附上请求体(必填) - Logs:故障前后服务器的输出(启动检查、引擎报错、
/health) - Instance type:如实写
trn2.48xlarge(必填) - Environment:
git rev-parse HEAD、neuron-ls、pip list中 neuron/torch/transformers 相关输出(必填) - Configuration:
--preset、--max-running等非默认 flag
⚠️ 注意:模板开头就提示——安全问题请走 SECURITY.md,不要发公开 issue。
性能回退报告(Performance Regression)
"变慢了"也是一种 Bug,有专门模板(源码见 .github/ISSUE_TEMPLATE/40-performance-regression.yml)。依据 CONTRIBUTING.md 的规则 2,一个可执行的回退报告必须包含:
- 哪个指标变慢(decode step、首 token、tokens/s、requests/min)及前后数值
- Last good version(最后一个正常版本/commit)与 First bad version
- 完整上下文:实例、Neuron SDK、
--preset与 flags、负载与形状、精度、精确的测量命令
🔒 如何安全地报告漏洞(Vulnerability)
安全问题的报告流程与普通 Bug 完全不同,核心原则只有一条:私有渠道,永不公开。
报告渠道与响应承诺
按 SECURITY.md:
- 在项目仓库发起 private security advisory(私有安全公告),或
- 发送邮件到 security@runanywhere.ai
一封合格的漏洞报告应包含 4 要素:
- 问题是什么,攻击者能拿它做什么
- 受影响的版本或 commit
- 复现步骤或 PoC(概念验证)
- 你建议的修复方式(可选但加分)
维护者承诺 3 个工作日内确认,并在修复前持续同步进展;同时请留出合理时间让他们先发布修复再公开披露。
支持版本策略
安全修复只进入 development 分支,并通过 main 的下一个 release 发布,且只有最新 release 获得安全修复——这意味着保持更新到最新版本本身就是安全实践。
📋 部署安全备忘(自查清单)
SECURITY.md 还明确了 TrnRT 的安全边界,部署时务必自查:
- TrnRT 是无认证的模型服务器:路由器默认监听
0.0.0.0,请放在自己的 proxy/gateway 之后,或传--host 127.0.0.1 serve模式下引擎只听127.0.0.1,/metrics不对外暴露- 张量并行 rank 走本地 TCP 与共享内存,保持 21000 及以上端口不向其他主机开放
- 服务容器需
--privileged才能访问 Neuron 设备,只在你可控的主机上运行 - 用 Hugging Face 仓库 id 服务时,务必
--revision固定版本,防止权重或 chat template 在脚下变化
📦 如何跟进 TrnRT 发布流程(Release 全流程)
理解发布流程,你能准确判断"我的修复什么时候能上线"。项目分支模型与发布机制记录在 docs/DEVELOPMENT.md。
分支模型:development 与 main
| 分支 | 接收什么 | 保护规则 |
|---|---|---|
development(默认) |
所有 PR,squash-merge | 1 名维护者批准 + 全部评论解决 + 4 个 CI job |
main |
仅 development 的晋升,只为发布 |
合并提交 only、仅 admin 可合并、需 "Promotion source" 检查 |
一次发布的 5 个步骤
- 在
development准备:一个 PR 提升 trnrt/init.py 的__version__,并把 CHANGELOG.md 的 Unreleased 条目移到新版本下;每个 release 都要重建编译缓存(版本变化可能改变图,缓存不匹配会导致启动失败) - 设备验证:在
trn2.48xlarge上跑 docker/check_image.py 的--device检查,并用tools/graph_equiv.py对比上一 release 看哪些图变了(CI 没有 Trainium runner,所以结果要写进 release PR) - 晋升(Promotion):从
development向main发一个标题为release: vX.Y.Z的 PR,由 admin 以合并提交合并。这次合并就是发布本身,没有单独的 tag 推送 - 自动化发布:push 到
main后release.yml运行,tools/release_plan.py 读取__version__与已有vX.Y.Ztag 判断动作(release / rerun / skip):在合并提交上创建 tag,生成含 sdist、wheel 与SHA256SUMS的 GitHub release;开启PUBLISH_PYPI后经可信发布(trusted publishing)上传 PyPI,开启PUBLISH_IMAGE后推送容器镜像 - 确认:run 的摘要会写明动作与 tag;发布串行执行,发布 job 失败可从 Actions 界面重跑(tag 与 release 已存在,流程幂等)
作为用户如何跟踪新版本
- 看 CHANGELOG.md:遵循 Keep a Changelog 格式 + SemVer,
Unreleased区是下一版的预告 - 看仓库的 CI 徽章(CI 状态、OpenSSF Scorecard)
- 记住关键提醒:每次 release 都要重建编译缓存,升级镜像时同步更新
✅ 新手参与贡献清单(3 步上手)
想从"用户"变成"贡献者",CONTRIBUTING.md 给出了三步起步:
make dev # 创建 .venv(Python 3.13 + CPU torch + 测试/lint 工具)
make check # lint + 类型检查 + CPU 测试套件
然后向 development 分支开 PR。几个要点:
- 标题格式:
<area>: <什么变了>,如router: answer a malformed body with 400;PR 是 squash-merge,标题即 commit 标题 - 标签帮你找活:找带
good first issue或help wanted标签的 issue 入手 - AI 评审不阻塞:CodeRabbit、cubic、Greptile 会在 PR 就绪后自动评审,状态永不阻塞合并,但它们的评论需要像其他评论一样逐条解决
- traced code 例外:改动
trnrt/kernels/、trnrt/models/等会影响编译图的代码需要tools/graph_equiv.py证据,其余宿主代码无此约束 - 紧急修复走同一条路:
development开 PR → 晋升 → patch release
小结
| 你的需求 | 一条路径 |
|---|---|
| 申请新模型 | Issue → Model request 模板(模型 id + revision、实例、负载) |
| 报告 Bug | Issue → Bug report 模板(命令、日志、环境、配置六要素) |
| 报告漏洞 | 私有 advisory 或 security@runanywhere.ai,3 个工作日响应 |
| 跟进发布 | CHANGELOG + development→main 晋升即发布,记得重建编译缓存 |
| 参与贡献 | make dev && make check → PR 到 development,标题 <area>: ... |
TrnRT 社区机制的设计哲学是"结构化 + 自动化":模板保证信息完整,CI 与发布流水线保证流程可重复。按上面的清单提交,你的问题和新模型申请都会更快被看见。