RunInfra SDK：面向生产环境的大模型推理部署官方SDK

本文介绍RunInfra官方SDK，这是一个同时支持TypeScript和Python的双语言SDK，为开发者提供统一的接口来部署和调用开源大语言模型，支持聊天补全、嵌入向量等功能，并具备完善的供应链安全验证机制。

• 原作者/维护者: RightNow-AI
• 来源平台: GitHub
• 原始标题: runinfra-sdk
• 原始链接: https://github.com/RightNow-AI/runinfra-sdk
• 发布时间: 2026年5月26日

RunInfra SDK的定位是成为连接开发者与RunInfra推理平台的官方桥梁。与直接使用HTTP API相比，SDK提供了类型安全、自动重试、错误处理等生产环境必需的功能。同时，双语言支持（TypeScript/JavaScript和Python）确保了不同技术栈的团队都能获得一致的开发体验。

从设计上看，该SDK遵循了现代云原生SDK的最佳实践：轻量级依赖、清晰的API设计、完善的文档和示例，以及对安全性的高度重视。

当前版本（v0.1.4）支持的功能包括：

聊天补全（Chat Completions）: SDK提供了与OpenAI兼容的接口，开发者可以使用熟悉的chat.completions.create方法调用部署在RunInfra上的模型。这种兼容性设计降低了迁移成本，现有使用OpenAI SDK的代码只需修改端点和认证信息即可切换。

嵌入向量（Embeddings）: 支持文本嵌入功能，适用于RAG（检索增强生成）等应用场景。SDK处理了批处理、编码和结果解析的细节。

图像和语音（实验性）: 图像生成、语音合成（TTS）和语音识别（ASR）功能目前处于实验阶段，API可能会在未来版本中调整。

语音管道（Voice Pipeline）: 这是一个实验性的端到端语音交互功能，目前尚未经过生产环境验证。

使用TypeScript的示例代码：

import { RunInfra } from "@runinfra/sdk";

const apiKey = process.env.RUNINFRA_API_KEY;
if (!apiKey) throw new Error("Set RUNINFRA_API_KEY before running this snippet.");

const client = new RunInfra({ apiKey });

const response = await client.chat.completions.create({
  model: "your-deployed-model-id",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices?.[0]?.message?.content);

Python版本同样简洁直观：

import os
from runinfra import RunInfra

api_key = os.environ.get("RUNINFRA_API_KEY")
if not api_key:
    raise RuntimeError("Set RUNINFRA_API_KEY before running this snippet.")

client = RunInfra(api_key=api_key)

response = client.chat.completions.create(
    model="your-deployed-model-id",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(response["choices"][0]["message"]["content"])

该项目在供应链安全方面投入了大量精力，值得其他开源项目借鉴：

可信发布（Trusted Publishing）: 通过GitHub Actions OIDC进行可信发布，每个版本都携带Sigstore支持的来源证明（provenance attestation），将发布包与特定的CI运行关联。用户可以通过npm和PyPI验证包的来源链。

代码扫描: 集成GitHub CodeQL进行默认代码扫描，并在受保护分支上强制执行安全检查。

制品验证: 发布流程包含多层次的制品验证：

• 构建后的npm tarball、Python wheel和sdist会被扫描，确保不包含源代码映射、调试信息、本地路径或敏感配置文件
• Python wheel的RECORD清单会被验证，确保每个文件都有SHA-256哈希和字节大小记录
• sdist的SOURCES.txt会被验证，防止过时的源清单隐藏文件

实时金丝雀测试（Live Canary）: 在发布前，SDK会针对生产API运行严格的实时测试，验证所有功能路径。测试报告包含详细的版本和摘要信息，用于发布决策。

SDK文档特别强调了浏览器安全：API密钥是Bearer Token，不应直接嵌入浏览器代码中。浏览器应用应该通过后端代理调用RunInfra，由服务器持有工作空间或管道范围的密钥。目前v0.1.4尚未支持临时浏览器令牌，开发者不应构建直接浏览器令牌流程，直到有范围的令牌、过期时间、审计日志和实时金丝雀覆盖到位。

当前SDK处于Beta阶段，主要功能（聊天补全和嵌入）已经过契约测试。图像、语音等高级功能仍处于实验阶段。项目文档明确指出了通往v1.0 GA的路径，包括严格的实时金丝雀契约要求。

对于希望采用该SDK的团队，建议关注项目的CHANGELOG和LIVE-CANARIES.md文档，了解功能稳定性和测试覆盖情况。