ONNX Runtime GenAI

状态

描述

使用 ONNX Runtime 运行生成式 AI 模型。该 API 提供了一种简单、灵活且高效的在设备上运行 LLM 的方式。它为 ONNX 模型实现了生成式 AI 循环，包括预处理和后处理、使用 ONNX Runtime 进行推理、logits 处理、搜索与采样、KV 缓存管理，以及用于工具调用的语法规范。

ONNX Runtime GenAI 为 Foundry Local、Windows ML 和 Visual Studio Code AI 工具包提供支持。

更多详细信息请参阅 ONNX Runtime 官网 的文档。

支持矩阵	当前支持	开发中	路线图
模型架构	AMD OLMo ChatGLM DeepSeek ERNIE 4.5 Fara Gemma gpt-oss Granite InternLM2 Llama Mistral Nemotron Phi (语言 + 视觉) Qwen (语言 + 视觉) SmolLM3 Whisper	Stable diffusion	多模态模型
API	Python C# C/C++ Java ^	Objective-C
操作系统	Linux Windows Mac Android		iOS
架构	x86 x64 arm64
硬件加速	CPU CUDA DirectML NvTensorRtRtx (TRT-RTX) OpenVINO QNN WebGPU		AMD GPU
特性	Multi-LoRA 连续解码 约束解码		推测解码

^ 需要从源代码构建

安装

请参阅 安装说明 或 从源代码构建

Phi-3 的 Python 示例代码

1. 下载模型

   huggingface-cli download microsoft/Phi-3-mini-4k-instruct-onnx --include cpu_and_mobile/cpu-int4-rtn-block-32-acc-level-4/* --local-dir .
   

2. 安装 API

   pip install numpy
   pip install --pre onnxruntime-genai
   

3. 运行模型

   import onnxruntime_genai as og
   
   model = og.Model('cpu_and_mobile/cpu-int4-rtn-block-32-acc-level-4')
   tokenizer = og.Tokenizer(model)
   stream = tokenizer.create_stream()
    
   # 默认设置一个合理的最大长度，
   # 否则它将被设置为整个上下文长度
   search_options = {}
   search_options['max_length'] = 2048
   search_options['batch_size'] = 1
   
   chat_template = '<|user|>\n{input} <|end|>\n<|assistant|>'
   
   text = input("Input: ")
   if not text:
      print("Error, input cannot be empty")
      exit()
   
   prompt = f'{chat_template.format(input=text)}'
   
   input_tokens = tokenizer.encode(prompt)
   
   params = og.GeneratorParams(model)
   params.set_search_options(**search_options)
   generator = og.Generator(model, params)
   
   print("Output: ", end='', flush=True)
   
   try:
      generator.append_tokens(input_tokens)
      while not generator.is_done():
         generator.generate_next_token()
         new_token = generator.get_next_tokens()[0]
         print(stream.decode(new_token), end='', flush=True)
   except KeyboardInterrupt:
         print("  --control+c pressed, aborting generation--")
   
   print()
   del generator
   

选择正确的示例版本

由于该项目仍在不断发展并持续添加新功能，main 分支中的示例可能并不总是与最新的稳定版完全一致。本节介绍了如何确保示例与相应版本之间的兼容性。

稳定版

按照 安装说明 安装软件包。例如，安装 Python 包：

pip install onnxruntime-genai

获取软件包版本：

Linux/Mac：

pip list | grep onnxruntime-genai

Windows：

pip list | findstr "onnxruntime-genai"

然后检出与该版本对应的示例分支：

# 克隆仓库
git clone https://github.com/microsoft/onnxruntime-genai.git && cd onnxruntime-genai
# 检出您正在使用的版本分支
git checkout v0.11.5
cd examples

夜间版（main 分支）

检出仓库的 main 分支：

git clone https://github.com/microsoft/onnxruntime-genai.git && cd onnxruntime-genai

按照这些 说明 从源代码构建。例如，构建 Python wheel：

python build.py

导航到 main 分支中的示例文件夹：

cd examples

安装夜间版 Python 构建：

# 将 onnxruntime-genai 替换为您想要安装的 Python 包
pip install --index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT-Nightly/pypi/simple/ onnxruntime-genai

路线图

请查看 讨论区，以请求新功能或为现有请求投票。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意一份贡献者许可协议 (CLA)，声明您有权并将您的贡献权利授予我们。有关详情，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地标记 PR（例如状态检查、评论）。只需按照机器人提供的指示操作即可。对于使用我们 CLA 的所有仓库，您只需执行一次此操作。

本项目已采用 微软开源行为准则。更多信息请参阅 行为准则常见问题解答，或如有任何其他疑问或意见，请联系 opencode@microsoft.com。

代码检查

本项目启用了 lintrunner 进行代码检查。您可以安装依赖项并初始化：

pip install -r requirements-lintrunner.txt
lintrunner init

这将在您的系统上安装 lintrunner，并下载所有必要的依赖项，以便在本地运行 linter。

格式化本地更改：

lintrunner -a

格式化所有文件：

lintrunner -a --all-files

商标

本项目可能包含项目、产品或服务的商标或标识。对微软商标或标识的授权使用须遵守并依据微软商标与品牌指南。在本项目的修改版本中使用微软商标或标识时，不得造成混淆或暗示微软的赞助关系。任何对第三方商标或标识的使用均应遵循该第三方的相关政策。

ONNX Runtime GenAI 快速上手指南

ONNX Runtime GenAI 是一个用于在本地设备运行生成式 AI 模型（如 LLM）的高性能库。它封装了完整的生成式 AI 循环，包括预处理、推理、日志处理、搜索采样、KV 缓存管理及工具调用的语法约束。

环境准备

系统要求

支持以下操作系统和架构：

• 操作系统: Linux, Windows, macOS, Android
• 架构: x86, x64, arm64
• 硬件加速: 支持 CPU, CUDA (NVIDIA), DirectML, OpenVINO, QNN, WebGPU 等。

前置依赖

• Python: 建议 Python 3.8 或更高版本。
• 包管理工具: pip
• 基础库: numpy (运行示例代码必需)

注意：本项目迭代迅速，示例代码需与安装的库版本严格对应。本指南基于最新稳定版流程编写。

安装步骤

1. 安装基础依赖

首先安装 numpy：

pip install numpy

2. 安装 ONNX Runtime GenAI

安装预发布版本（通常包含最新的功能支持）：

pip install --pre onnxruntime-genai

国内加速提示：如果下载速度慢，可使用清华或阿里镜像源：

pip install --pre onnxruntime-genai -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 验证版本（可选但推荐）

由于 main 分支的示例可能与稳定版不兼容，建议确认已安装的版本号：

pip list | grep onnxruntime-genai
# Windows 用户使用: pip list | findstr "onnxruntime-genai"

若需运行特定版本的示例代码，请前往 GitHub 仓库 checkout 对应的 tag（例如 git checkout v0.11.5）。

基本使用

以下以微软 Phi-3 模型为例，演示如何下载模型并运行一个简单的对话生成任务。

第一步：下载模型

使用 huggingface-cli 下载 Phi-3 的 ONNX 量化版本（针对 CPU 和移动端优化）：

huggingface-cli download microsoft/Phi-3-mini-4k-instruct-onnx --include cpu_and_mobile/cpu-int4-rtn-block-32-acc-level-4/* --local-dir .

国内加速提示：如果无法访问 Hugging Face，可设置镜像环境变量：

export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download microsoft/Phi-3-mini-4k-instruct-onnx --include cpu_and_mobile/cpu-int4-rtn-block-32-acc-level-4/* --local-dir .

第二步：运行代码

创建文件 run_phi3.py，填入以下代码：

import onnxruntime_genai as og

# 加载模型路径
model = og.Model('cpu_and_mobile/cpu-int4-rtn-block-32-acc-level-4')
tokenizer = og.Tokenizer(model)
stream = tokenizer.create_stream()
 
# 配置生成参数
search_options = {}
search_options['max_length'] = 2048
search_options['batch_size'] = 1

# 定义聊天模板 (Phi-3 特定格式)
chat_template = '<|user|>\n{input} <|end|>\n<|assistant|>'

text = input("Input: ")
if not text:
   print("Error, input cannot be empty")
   exit()

prompt = f'{chat_template.format(input=text)}'

# 编码输入
input_tokens = tokenizer.encode(prompt)

params = og.GeneratorParams(model)
params.set_search_options(**search_options)
generator = og.Generator(model, params)

print("Output: ", end='', flush=True)

try:
   generator.append_tokens(input_tokens)
   while not generator.is_done():
      generator.generate_next_token()
      new_token = generator.get_next_tokens()[0]
      # 流式解码输出
      print(stream.decode(new_token), end='', flush=True)
except KeyboardInterrupt:
      print("  --control+c pressed, aborting generation--")

print()
del generator

第三步：执行

在终端运行脚本：

python run_phi3.py

输入问题后，模型将流式输出回答。

---

更多模型架构支持（如 Llama, Qwen, Gemma 等）及高级用法，请参考 ONNX Runtime 官方文档。