> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# ONNX：生成式AI运行时
- URL: https://www.hubwiz.com/blog/onnx-runtime-genai/
- Published: 2026-01-27T07:34:48.000Z
- Updated: 2026-01-27T07:34:48.000Z
- Description: ONNX Runtime GenAI 使你能够在想要的地方运行模型：如果有 GPU 就用 GPU，没有就用 CPU。所有这些都不需要更改一行代码.
- Author: admin
- Tags: LIBRARY, ONNX-RUNTIME-GENAI, #Import 2026-10-14 14:41

有时一个小模型就能解决问题。而且你并不总是需要 GPU。有理由直接在 CPU 上运行"工具"任务。有时你根本无法拥有 GPU。或者你想保持数据本地化。或者只是想保持架构简单。

这就是 [ONNX Runtime GenAI](https://github.com/microsoft/onnxruntime-genai?ref=hubwiz.com) 发挥作用的地方。它使你能够在想要的地方运行模型：如果有 GPU 就用 GPU，没有就用 CPU。所有这些都不需要更改一行代码。在这篇文章中，我将展示它如何工作，包括在 [Google Cloud Run](https://cloud.google.com/run?ref=hubwiz.com) 上托管你的模型。你可以在 [onnx-inference](https://github.com/kweinmeister/onnx-inference?ref=hubwiz.com) 存储库中找到所有示例代码。

## 1、起源：可移植的 ML 模型

这一切始于 2017 年 9 月。行业领导者意识到 ML 工具的碎片化正在伤害每个人，因此 ONNX 作为一个共享标准启动了。其推广很简单：模型的"通用翻译器"。你可以在首选框架中训练，导出到通用标准，并在各种硬件目标上高效运行模型。

行业没有浪费时间。到年底，更多公司加入进来，2018 年微软开源了 ONNX Runtime，这个引擎旨在在任何硬件上高效*运行*这些模型。它于 2019 年毕业成为 [Linux Foundation AI 项目](https://lfaidata.foundation/projects/onnx/?ref=hubwiz.com)，巩固了其作为开放标准的地位。

## 2、方向：可移植的 LLMs

当 LLM 爆发在 2023 年左右袭来时，ONNX 面临新的挑战。传统模型是无状态的：输入进去，预测出来。LLMs 不同。它们健谈。它们有记忆。它们逐个 token 生成文本，需要管理"KV 缓存"来记住对话上下文。

标准的 ONNX 运行时并不是为这个循环构建的。

所以 2024 年，社区发布了 [onnxruntime-genai](https://github.com/microsoft/onnxruntime-genai?ref=hubwiz.com)。它用 LLMs 需要的所有特定逻辑包装了核心运行时：分词、生成循环、搜索策略如束搜索，以及状态管理。

快进到 2026 年，我们现在在 [Hugging Face](https://huggingface.co/onnx-community?ref=hubwiz.com) 上有预量化 ONNX 模型库。你可以从货架上拉出模型并立即运行，无需任何训练或格式转换。

## 3、使用库

`onnxruntime-genai` 的好处是它为你处理生成。如果你尝试使用原始 ONNX Runtime 来做这件事，你需要编写手动循环将输出 token 作为输入反馈。

现在它看起来是这样的：

```python
import onnxruntime_genai as og
# 加载模型（此路径自动适用于 CPU、GPU 或移动设备）
model = og.Model('path/to/model')
tokenizer = og.Tokenizer(model)
# 配置你想要的搜索方式
params = og.GeneratorParams(model)
params.set_search_options(max_length=256, batch_size=1)
# 生成循环
generator = og.Generator(model, params)
generator.append_tokens(tokenizer.encode(prompt))
while True:
    generator.generate_next_token()
    if generator.is_done():
        break

    # 边生成边解码和打印
    token = generator.get_next_tokens()[0]
    print(tokenizer.decode(token), end='', flush=True)

```

它在这里做了很多繁重的工作：处理 KV 缓存、应用你的搜索策略（贪婪、top-p 等），并将操作路由到最佳可用硬件（CUDA、CoreML 或 CPU）。

## 4、硬件、模型和量化

自从 LLMs 的早期以来，一些事情发生了变化。处理器变快了，模型在更小的情况下仍然具有令人难以置信的能力。

然后是**量化**。我们不再受限于以完整的 32 位精度运行模型。像 INT4 量化这样的技术可以大大压缩权重，而对精度的影响令人惊讶地小。

我用 [onnx-inference](https://github.com/kweinmeister/onnx-inference?ref=hubwiz.com) 测试了很多模型。注意这些小模型能够识别结构，但不适合知识密集型任务。

对于非常简单的任务，你可以使用像 [SmolLM2–135M](https://huggingface.co/onnx-community/SmolLM2-135M-ONNX?ref=hubwiz.com) 这样的微小模型。它非常适合基本完成或分类。

对于更复杂的任务，你会想要一个更大的模型。[Qwen 3–0.6B](https://huggingface.co/qwen/Qwen-3.0-0.6B?ref=hubwiz.com) 为多几亿个参数提供了更多的能力。

当你在 CPU 上考虑超过 500M 参数的模型时，你需要仔细监控上下文窗口、最大 token 和你可以容忍的延迟。

## 5、构建可移植服务器

将推理逻辑包装在轻量级服务器中使其普遍可访问。无论语言如何，都可以从任何服务轻松调用。我的存储库中的代码提供了一个 [FastAPI](https://fastapi.tiangolo.com/?ref=hubwiz.com) 服务器，正是这样做的。

主类是 `OnnxTextGenerator`，它处理推理逻辑：

```python
from inference import OnnxTextGenerator

# 自动检测硬件
generator = OnnxTextGenerator()

# 简单运行
result = generator.generate(
    prompt="Explain quantum computing like I'm five:",
    max_new_tokens=100,
    temperature=0.7
)

print(result['generated_text'])

```

对于实时应用程序，你不能等待整个答案。你可以流式传输它：

```python
for chunk, metadata in generator.stream_generate(
    prompt="Write a haiku about Docker:",
    max_new_tokens=50,
    temperature=0.8
):
    print(chunk, end='', flush=True)

```

每个函数都作为端点暴露在 FastAPI 中：

```python
@app.post("/generate")
async def generate(request: GenerateRequest):
    result = generator.generate(
        prompt=request.prompt,
        max_new_tokens=request.max_new_tokens,
        temperature=request.temperature
    )
    return {
        "generated_text": result["generated_text"],
        "tokens_generated": result["tokens_generated"],
        "finish_reason": result["finish_reason"]
    }

```

我想要一个"就能用"的东西，所以初始化器自动寻找最佳硬件执行提供程序：[CUDA](https://developer.nvidia.com/cuda-zone?ref=hubwiz.com)（NVIDIA GPU）→ [CoreML](https://developer.apple.com/documentation/coreml?ref=hubwiz.com)（Apple Silicon）→ CPU（通用回退）。

## 6、容器化策略

对于像前面列出的那些较小模型，一个方便的模式是**将模型直接烘焙到镜像中**。这使得它们在部署后立即可用，而无需等待下载。

这是我使用的 Dockerfile 的简化视图：

```dockerfile
FROM python:3.12-slim

COPY requirements.txt .
RUN pip install -r requirements.txt

ARG MODEL_ID=onnx-community/SmolLM2-135M-Instruct-ONNX
RUN hf download ${MODEL_ID} --local-dir /app/model

COPY . /app
WORKDIR /app

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"]

```

当你加载此容器时，模型已经在磁盘上了。它立即启动，在没有互联网访问的情况下工作。

## 7、在 Google Cloud Run 上实现无服务器

Cloud Run 非常适合使用小模型的应用程序。当你不使用它时，它扩展到零，所以你停止为资源付费。由于我们使用 CPU，我们也不需要提供 GPU 实例。

### 7.1 从源代码部署

我们可以直接从源代码部署。以下命令使用 Google Cloud Build 构建容器，并在一步中将其部署到 Cloud Run。

我们故意在这里设置了一些特定标志。我们分配 **2 个 CPU**，因为推理是计算密集型的，以及 **4Gi 内存** 以舒适地容纳小模型和 KV 缓存。我们还将**并发设置为 4**，这允许实例处理一些同时请求而不会颠簸缓存。

```bash
gcloud run deploy onnx-inference \
    --allow-unauthenticated \
    --concurrency 4 \
    --cpu 2 \
    --labels dev-tutorial=onnx-inference \
    --memory 4Gi \
    --region us-central1 \
    --source .

```

### 7.2 测试

部署完成后，我们需要获取新服务的安全 URL。然后我们可以使用简单的 curl 命令进行测试。

```bash
SERVICE_URL=$(gcloud run services describe onnx-inference \
    --region $REGION \
    --format 'value(status.url)')

curl -X POST "$SERVICE_URL/generate" \
    -H "Content-Type: application/json" \
    -d '{"prompt": "Why is efficient AI important?", "max_new_tokens": 50}'

```

### 7.3 故障排除

一些事情可能会绊倒你：

- **缺失** [**genai\_config.json**](https://onnxruntime.ai/docs/genai/reference/config.html?ref=hubwiz.com)：并非所有 Hugging Face ONNX 模型都包含 GenAI 库的配置。我的库尝试在缺失时推断配置，但最好使用已有配置的模型。
- **执行提供程序**：示例当前包括 CUDA、CoreML 和 CPU，但添加其他提供程序（如 [TensorRT](https://onnxruntime.ai/docs/execution-providers/TensorRT-ExecutionProvider.html?ref=hubwiz.com) 或 [OpenVINO](https://onnxruntime.ai/docs/execution-providers/OpenVINO-ExecutionProvider.html?ref=hubwiz.com)）是直截了当的。
- **参数**：当你扩大 `max_new_tokens` 时，KV 缓存增长，注意力机制执行更多计算。密切关注内存使用和延迟。

## 8、结束语

较小的模型已经走了很长的路。通过 ONNX Runtime GenAI 和适度量化，你可以在几年前似乎不可能的地方运行有能力的 LLMs。

这开辟了一整套新的应用程序：完全私有的本地助手、智能边缘设备，以及几乎没有成本维护的无服务器 API。

如果你想尝试一下，大约需要 5 分钟开始。你可以从 [GitHub 上的 onnx-inference 存储库](https://github.com/kweinmeister/onnx-inference?ref=hubwiz.com) 获取代码，查看官方 [ONNX Runtime GenAI 文档](https://onnxruntime.ai/docs/genai?ref=hubwiz.com) 了解更深入的详细信息，或浏览 [Hugging Face ONNX Community](https://huggingface.co/onnx-community?ref=hubwiz.com) 找到你的下一个模型。

---

原文链接: [Run LLMs anywhere: Local and CPU inference with ONNX Runtime GenAI](https://medium.com/google-cloud/run-llms-anywhere-local-and-cpu-inference-with-onnx-runtime-genai-9bc34dbf0d7d?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处