人工智能控制器接口（AICI）

LLGuidance库 是 AICI 的一个积极维护的演进与专业化版本，如果您只需要受限解码功能，推荐使用该库。

人工智能控制器接口（AICI）使您能够构建实时约束和引导大型语言模型（LLM）输出的控制器。这些控制器是灵活的程序，能够实现受限解码、动态编辑提示和生成文本，以及协调多个并行生成任务的执行。控制器在逐标记解码过程中融入自定义逻辑，并在 LLM 请求期间保持状态。这使得各种控制器策略成为可能，从基于编程或查询的解码，到多智能体对话，从而与 LLM 本身紧密集成并高效执行。

AICI 的目的是让构建和试验现有及全新的控制器策略以改进 LLM 生成变得容易。 通过抽象底层 LLM 推理和服务引擎的实现细节，AICI 旨在简化控制器开发，使编写快速控制器更加容易，并促进跨 LLM 推理和服务引擎的兼容性。

AICI 既适用于本地执行，也适用于云端执行，包括（最终）多租户 LLM 部署。控制器被实现为轻量级 WebAssembly（Wasm）模块，在与 LLM 推理引擎相同的机器上运行，利用 CPU 资源，而 GPU 则专注于标记生成任务。AICI 是推理栈中的一层，旨在允许 Guidance、LMQL 等控制库在其之上运行，从而获得效率和性能提升，以及跨 LLM 推理和服务引擎的可移植性。

目前，AICI 已与 llama.cpp、HuggingFace Transformers 和 rLLM（自定义基于 tch 的 LLM 推理引擎）集成，vLLM 的集成也在进行中。

AICI 具有以下特点：

• 灵活性：控制器可以用任何可编译为 Wasm 的语言编写（Rust、C、C++ 等），也可以在 Wasm 内解释执行（Python、JavaScript 等）。
• 安全性：控制器运行在沙盒环境中，无法访问文件系统、网络或其他资源。
• 高性能：Wasm 模块被编译为原生代码，与 LLM 推理引擎并行运行，对生成过程仅引入极小的开销。

AICI 是一个原型，由 微软研究院 设计并构建。

目录

• 人工智能控制器接口（AICI）
• 快速入门：示例 walkthrough
  • 开发环境设置
  • 构建并启动 rLLM 服务器和 AICI 运行时
  • 使用 AICI 控制器控制 AI 输出
• 全面指南：深入探索
• 架构
• 安全性
• 性能
• 灵活性
• 致谢
• 贡献
• 商标

快速入门：示例 walkthrough

在本快速入门中，我们将引导您完成以下步骤：

• 设置 rLLM 服务器 和 AICI 运行时。
• 构建并部署一个 控制器。
• 使用 AICI 控制 LLM 输出，以便在生成文本时 根据特定规则自定义 LLM 行为。

开发环境设置

要编译 AICI 组件，您需要为 Rust 设置开发环境。对于本快速入门，您还需要 Python 3.11 或更高版本来创建控制器。

Windows WSL / Linux / macOS

[!NOTE] Windows 用户：请使用 WSL2 或附带的 devcontainer。添加原生 Windows 支持的计划已在 此处跟踪。

macOS 用户：请确保已安装 XCode 命令行工具，可通过运行 xcode-select -p 来检查；若未安装，请运行 xcode-select --install。

CUDA：CUDA 构建依赖于特定的 libtorch 安装。强烈建议使用附带的 devcontainer。

如果您使用 devcontainer，可以直接跳至下一节 构建并启动 rLLM 服务器和 AICI 运行时。

使用系统包管理器安装仓库中构建代码所需的工具，包括 git、cmake 和 ccache。

例如，在 WSL / Ubuntu 中使用 apt：

sudo apt-get install --assume-yes --no-install-recommends \
    build-essential cmake ccache pkg-config libssl-dev libclang-dev clang llvm-dev git-lfs

或者在 macOS 上使用 Homebrew：

brew install git cmake ccache

然后按照 此处 和 此处 的说明安装 Rust、Rustup 和 Cargo：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安装完成后，请通过在终端中运行 rustup --version 来验证命令是否可用。如果命令未被识别，请尝试打开一个新的终端会话。

接下来安装 wasm32-wasi Rust 组件：

rustup target add wasm32-wasi

如果您已经安装了 Rust，或者 Cargo 报告版本过旧，请运行：

rustup update

最后，为了使用 Python 控制器和脚本（如本教程），请运行以下命令安装所需软件包：

pip install pytest pytest-forked ujson posix_ipc numpy requests

构建并启动 rLLM 服务器和 AICI 运行时

rLLM 服务器有两个后端，一个基于 libtorch 和 CUDA（rllm-cuda），另一个基于 llama.cpp（rllm-llamacpp）。

rllm-cuda 后端仅适用于计算能力为 8.0 或更高的 NVIDIA GPU（A100 及更高版本；RTX 30x0 及更高版本），并且需要对 libtorch 进行较为复杂的配置——强烈建议使用随附的 devcontainer。虽然本指南重点介绍 rllm-llamacpp 后端，但构建步骤与 rllm-cuda 相同，只是文件夹名称略有不同。

在完成上述 开发环境设置 后，克隆 AICI 仓库，并按照以下步骤继续操作。

使用以下命令构建并运行 aicirt 和 rllm-llamacpp：

cd rllm/rllm-llamacpp
./server.sh phi2

您可以传递其他模型名称作为参数（运行 ./server.sh 而不带参数可查看可用模型）。您也可以使用指向 .gguf 文件的 HuggingFace URL 或本地路径。

./server.sh orca

有关 rllm-llamacpp 的更多详细信息，请参阅 这里。

rLLM 服务器提供 HTTP 接口，用于配置任务和处理请求。您还可以使用此接口快速验证其状态。例如，如果您打开 http://127.0.0.1:4242/v1/models，您应该会看到：

{
  "object": "list",
  "data": [
    {
      "object": "model",
      "id": "TheBloke/phi-2-GGUF",
      "created": 946810800,
      "owned_by": "owner"
    }
  ]
}

这表明所选模型已加载。

使用 AICI 控制器控制 AI 输出

AICI 允许托管称为 控制器 的自定义逻辑，这些控制器可以启动、终止并与 LLM 的标记生成进行交互。控制器接收输入参数，对其进行处理，并返回包含日志、LLM 标记和变量的结果。

该仓库包含一些示例，特别是：

• jsctrl：一个接受 JavaScript 代码作为输入以执行的控制器。该代码可以与模型交互以生成文本和标记。
• pyctrl：一个接受 Python 代码作为输入以执行的控制器。该代码同样可以与模型交互以生成文本和标记。

在本示例中，我们将使用 pyctrl 来管理使用简单 Python 脚本 的标记生成。如果您愿意，可以 构建并上传 pyctrl，不过默认情况下，服务器会自动从 GitHub 下载 最新版本 的 pyctrl。

通常，控制器需要构建和部署，而脚本（Python 或 JavaScript）则随每次请求一起发送。

下图展示了 rLLM 服务器、AICI 运行时和控制器之间的关系：

erDiagram
    Host    ||--|{ CPU : ""
    Host    ||--|{ GPU : ""
    
    CPU     ||--|| "rLLM Server" : execute
    CPU     ||--|{ "AICI Runtime" : execute

    "AICI Runtime" ||--|| "Controller" : instantiate

    GPU     ||--|{ "LLM token generation" : execute

控制 LLM 标记生成

假设我们希望模型生成一个符合特定格式且仅包含五项的列表。

通常，实现这一点需要提示工程，即精心设计提示，明确指示，例如：

最受欢迎的五种交通工具是什么？
请以编号列表的形式返回结果。
不要添加解释，只需列出内容。

提示也会因使用的模型而异，因为每个模型倾向于添加解释，并且对指令的理解方式也不同。

借助 AICI，我们可以将控制权交还给代码，从而简化提示，例如：

最受欢迎的交通工具有哪些？

然后通过代码来：

1. 将列表限制为 5 项
2. 阻止模型添加任何初始解释
3. 格式化为编号列表
4. 阻止模型在列表之后添加任何额外文本。

让我们创建一个名为 list-of-five.py 的 Python 文件，内容如下：

import pyaici.server as aici

# 强制模型生成格式良好的 5 项列表，例如：
#   1. 名称 1
#   2. 名称 2
#   3. 名称 3
#   4. 名称 4
#   5. 名称 5
async def main():
    
    # 这是我们想要运行的提示。
    # 注意提示中并未提及交通工具的数量或结果的格式。
    prompt = "最受欢迎的交通工具有哪些？\n"

    # 告诉模型生成提示字符串，即从“待完成”的提示开始
    await aici.FixedTokens(prompt)

    # 记录当前标记生成过程中的位置
    marker = aici.Label()

    for i in range(1,6):
      # 告诉模型生成列表编号
      await aici.FixedTokens(f"{i}.")

      # 等待模型生成交通工具名称并以换行符结束
      await aici.gen_text(stop_at = "\n")

    await aici.FixedTokens("\n")

    # 将生成的标记存储到结果变量中
    aici.set_var("result", marker.text_since())

aici.start(main())

运行该脚本与发送提示并没有太大区别。在这种情况下，我们同时发送了控制逻辑和指令。

要查看最终结果，请执行以下命令：

./aici.sh run list-of-five.py

结果：

Running with tagged AICI Controller: gh:microsoft/aici/pyctrl
[0]: FIXED '最受欢迎的交通工具有哪些？\n'
[0]: FIXED '1.'
[0]: GEN ' 汽车\n'
[0]: FIXED '2.'
[0]: GEN ' 摩托车\n'
[0]: FIXED '3.'
[0]: GEN ' 自行车\n'
[0]: FIXED '4.'
[0]: GEN ' 卡车\n'
[0]: FIXED '5.'
[0]: GEN ' 船舶\n'
[0]: FIXED '\n'
[DONE]
[Response] 最受欢迎的交通工具有哪些？
1. 汽车
2. 摩托车
3. 自行车
4. 卡车
5. 船舶

response saved to tmp/response.json
Usage: {'sampled_tokens': 16, 'ff_tokens': 37, 'cost': 69}
Timing: {'http_response': 0.05193686485290527, 'data0': 0.05199289321899414, 'first_token': 0.0658726692199707, 'last_token': 0.1784682273864746}
Tokens/sec: {'prompt': 861.0913072488067, 'sampling': 89.65181217019571}
Storage: {'result': '1. 汽车\n2. 摩托车\n3. 自行车\n4. 卡车\n5. 船舶\n\n'}

综合指南：深入探索

本仓库包含多个组件，具体需要哪些组件取决于您的使用场景。

您可以 使用现有的控制器模块。 我们提供了 PyCtrl 和 JsCtrl，分别允许您使用服务器端的 Python 和 JavaScript 编写控制器脚本。pyaici 包（位于 ./py/pyaici）中包含 aici 命令行工具，该工具使您能够通过任何控制器 上传并运行脚本（我们还为感兴趣者提供了 REST API 定义）。

🧑‍💻 PyCtrl 脚本的 Python 示例代码 以及 JSCtrl 的 JavaScript Hello World 示例

我们预计会有基于控制器构建的 库。我们在 promptlib（位于 ./py/promptlib）中提供了一个示例——这是一个客户端 Python 库，它通过 pyaici 包与 DeclCtrl（位于 ./controllers/declctrl）进行交互。

🧑‍💻 使用 PromptLib 与 DeclCtrl 交互的示例笔记本。

这些控制器可以在云端或本地的 AICI 支持的 LLM 推理引擎上运行。您也可以 在本地运行提供的参考引擎 (rLLM)，可以选择使用 libtorch+CUDA 或 llama.cpp 后端。

要 开发一个新的控制器，可以使用 Rust 的 入门项目，该项目展示了如何使用 aici_abi（位于 ./controllers/aici_abi）库，该库简化了对 低层级 AICI 接口（详见 controllers/aici_abi/README.md#low-level-interface）的实现。

🧑‍💻 一个极简的新控制器示例代码，帮助您快速入门。

要 为新的 LLM 推理引擎添加 AICI 支持，您需要实现与 AICI 运行时 通信的 协议 中的 LLM 端部分（详见 docs/aicirt-proto.md）。

最后，如果您希望修改任何提供的组件，欢迎提交 PR！

架构

AICI 将 LLM 推理引擎与控制器相互抽象化，如图所示。图中的圆角节点代表未来的发展方向。在此基础上还可以构建更多层次——我们已经提供了 promptlib，但我们坚信，Guidance、LMQL、SGLang、Outlines、jsonformer、LMFE 等工具也可以运行在 AICI 之上（无论是使用自定义控制器，还是利用 PyCtrl 或 JsCtrl）。

graph TD
    PyCtrl -- AICI --> aicirt[AICI-runtime]
    JsCtrl -- AICI --> aicirt
    guidance([GuidanceCtrl]) -- AICI --> aicirt
    lmql([LMQL Ctrl]) -- AICI --> aicirt
    aicirt -- POSIX SHM --> rLLM
    aicirt -- POSIX SHM --> llama[llama.cpp]
    aicirt -- POSIX SHM --> pyaici
    pyaici -- Python --> vLLM(vLLM)
    pyaici -- Python --> hf[HF Transformers]

pyaici 包（位于 py/pyaici）使得将 AICI 集成到基于 Python 的 LLM 推理引擎中更加容易。请参阅与 HuggingFace Transformers 的集成示例，但请注意，该集成不支持分叉（即并行生成多条序列）。目前，vLLM REST 服务器 已经过时，请暂时使用 rLLM-cuda 或 rLLM-llama.cpp。

安全性

• aicirt 在独立进程中运行，并且可以以不同于 LLM 引擎的用户身份运行。
• Wasm 模块由 Wasmtime 进行沙箱隔离。
• Wasm 模块仅能访问 aici_host_* 函数，这些函数在 hostimpl.rs 中实现。
• aicirt 还暴露了一个部分 WASI 接口；然而，除了 fd_write 函数外，几乎所有函数都是空操作，其中 fd_write 会将文件描述符 1 和 2（即标准输出和标准错误）重定向以打印调试信息。
• 每个 Wasm 模块都在独立进程中运行，这有助于缓解 Spectre/Meltdown 攻击，并允许对 CPU 使用率进行限制。

特别地，Wasm 模块无法访问文件系统、网络或其他任何资源。它们也不能创建线程或访问任何定时器（这一点对于防止 Spectre/Meltdown 攻击至关重要）。

性能

AICI 控制器中的大部分计算都在 CPU 上进行，与 GPU 上的 logits 生成并行执行。生成过程是分步进行的，每一步都会为批次中的每条序列并行生成下一个 token 的 logits（通常在 1 到 50 条序列之间）。这一过程涉及从 GPU 内存中读取整个模型和批次中各序列的 KV 缓存。为了获得最佳的批处理吞吐量，模型和 KV 缓存应占用 GPU 内存的大部分空间，而在 A100 GPU（80GB）上，读取全部内存大约需要 40 毫秒。

因此，每一步的生成大约需要 20–50 毫秒。通过精心设计，这完全足够在编译为 Wasm 的 Rust 代码中计算出允许的 token 集合。这些集合可以通过 Rust 原生方式，或者通过我们提供的 Python 或 JavaScript 解释器来组合。

例如，在 Llama 模型的 32,000 词汇表中计算允许的 token 集合所需的时间如下：

• C 语言的 Yacc 文法约为 2.0 毫秒；
• 正则表达式约为 0.3 毫秒；
• 从 4KB 字符串中提取子字符串约束约为 0.2 毫秒。

以上数字针对单条序列，但由于每条序列都在独立进程中处理，因此如果核心数多于序列数（这通常是情况），这些时间不会发生变化。此外，这些时间还包括调用 Wasm 中实现的 Python 解释器，然后再回到由 Rust 生成的用于约束本身的 Wasm 代码的开销。所有这些开销都远低于 20–50 毫秒的预算，因此完全不会影响生成时间。

在采样关键路径上也存在一些额外开销。当并行执行 10 条序列时，每步采样的开销约为 0.3 毫秒（与所使用的约束无关）。而当并行执行 40 条序列时，这个开销会上升至约 0.7 毫秒（不过目前尚未完全优化）。

WebAssembly 的设计目标之一就是尽可能减少与原生代码相比的开销。根据我们的经验，经过 高度优化 的 Rust 代码在 Wasmtime 中运行时，其速度仅比原生代码慢不到两倍。这比 JavaScript 或 Python 快 10 到 100 倍。

所有测量均在配备 nVidia A100 GPU（80GB VRAM）的 AMD EPYC 7V13 服务器上完成。

灵活性

AICI 运行时提供的低级别接口支持以下功能：

• 在每个生成的标记之前、期间和之后与 LLM 推理引擎进行交互
• 将解码限制在一组特定的标记上
• 将 KV 缓存回溯到先前的状态
• 一次性快进多个标记（如果这些标记已知）
• 将生成过程分支为多个路径
• 通过共享变量在不同分支之间进行通信
• 提供用于在标记和字节字符串之间相互转换的实用函数

该接口可以被任何编译为 Wasm 的语言所使用。

本仓库提供了一个 Rust 库，使得在 Rust 中实现控制器变得简单，并且提供了针对特定约束条件的高效实现（如正则表达式、Yacc 文法、子字符串）。我们还提供了 Python 和 JavaScript 解释器，允许将这些约束条件组合在一起。所有这些都可以轻松扩展。

致谢

• Flash Attention 核心 源自 flash-attention 仓库；参见 BSD 许可证
• 分页注意力核心 源自 vLLM 仓库；参见 Apache 许可证
• OpenAI API 定义 源自并修改自 candle-vllm；参见 MIT 许可证
• cache_engine.rs、config.rs 和 scheduler.rs 均松散地基于 vLLM
• llama.rs、phi.rs 和 logits.rs 基于 candle-transformers
• 特定的 Python 库 文件源自 RustPython（因为我们仅使用其中的一部分）
• 示例 ANSI C 文法 c.y 基于 Jeff Lee（1985 年）提供的 https://www.lysator.liu.se/c/ANSI-C-grammar-y.html

引用本软件包

如果您认为 AI 控制器接口及其在 LLM 推理栈中定义新层的理念有用，请使用以下引用方式来引用本软件包：

• Michal Moskal, Madan Musuvathi, Emre Kıcıman. AI 控制器接口, (2024), GitHub 仓库. https://github.com/microsoft/aici

Bibtex:

@misc{Moskal2024,
  author = {Moskal, Michal and Musuvathi, Madan and {K\i c\i man}, Emre},
  title = {{AI 控制器接口}},
  year = {2024},
  publisher = {{GitHub}},
  journal = {{GitHub} 仓库},
  howpublished = {\url{https://github.com/microsoft/aici/}}
}

贡献

本项目欢迎各种贡献和建议。大多数贡献都需要您签署一份贡献者许可协议（CLA），声明您有权并将您的贡献授予我们使用。有关详细信息，请访问 https://cla.opensource.microsoft.com。

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

本项目已采用 微软开源行为准则。更多信息请参阅 行为准则常见问题解答 或发送邮件至 opencode@microsoft.com 咨询更多问题或意见。

商标

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

AICI 快速上手指南

AICI (Artificial Intelligence Controller Interface) 是一个用于构建控制器的接口，能够实时约束和指导大语言模型 (LLM) 的输出。它通过轻量级的 WebAssembly (Wasm) 模块运行，支持与 LLM 推理引擎紧密集成，实现受限解码、动态提示编辑等功能。

注意：如果您仅需受限解码功能，推荐使用 AICI 的演进版本 LLGuidance。

环境准备

系统要求

• 操作系统：Linux、macOS 或 Windows (需使用 WSL2)。
  • Windows 用户：请使用 WSL2 或项目提供的 devcontainer。原生 Windows 支持尚在开发中。
  • macOS 用户：确保已安装 XCode 命令行工具 (xcode-select --install)。
• 硬件：
  • CPU：通用支持。
  • GPU (可选)：若使用 rllm-cuda 后端，需 NVIDIA GPU (计算能力 8.0+, 如 A100, RTX 30x0 系列)。
• 软件版本：
  • Python 3.11 或更高版本
  • Rust (最新稳定版)

前置依赖

请使用系统包管理器安装以下基础构建工具：

Ubuntu / WSL:

sudo apt-get install --assume-yes --no-install-recommends \
    build-essential cmake ccache pkg-config libssl-dev libclang-dev clang llvm-dev git-lfs

macOS (Homebrew):

brew install git cmake ccache

安装 Rust 及 Wasm 目标组件:

# 安装 Rustup 和 Cargo
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 重新加载环境变量或打开新终端后，添加 wasm32-wasi 目标
rustup target add wasm32-wasi

# 如有需要，更新 Rust 工具链
rustup update

安装 Python 依赖:

pip install pytest pytest-forked ujson posix_ipc numpy requests

安装与启动

本指南以 rllm-llamacpp 后端为例（兼容性最好，无需复杂 CUDA 配置）。

1. 克隆仓库并启动服务

克隆 AICI 仓库后，进入 rllm-llamacpp 目录并启动服务器。以下命令将自动下载并运行 phi2 模型（也可替换为其他模型名称或本地 .gguf 文件路径）。

cd rllm/rllm-llamacpp
./server.sh phi2

注：运行 ./server.sh 不带参数可查看可用模型列表。

2. 验证服务状态

服务器启动后提供 HTTP 接口。访问 http://127.0.0.1:4242/v1/models，若看到如下 JSON 响应，说明模型加载成功：

{
  "object": "list",
  "data": [
    {
      "object": "model",
      "id": "TheBloke/phi-2-GGUF",
      "created": 946810800,
      "owned_by": "owner"
    }
  ]
}

基本使用

AICI 的核心是通过 Controller (控制器) 来控制 LLM 的生成过程。您可以编写 Python 或 JavaScript 脚本作为控制逻辑，无需复杂的提示词工程即可强制模型遵守格式。

示例：生成固定格式的 5 项列表

创建一个名为 list-of-five.py 的文件，内容如下。该脚本将强制模型生成一个包含 5 个项目的编号列表，并阻止模型添加额外的解释文字。

import pyaici.server as aici

async def main():
    
    # 定义基础提示词，无需指定数量或格式
    prompt = "What are the most popular types of vehicles?\n"

    # 让模型先完成提示词部分
    await aici.FixedTokens(prompt)

    # 标记当前生成位置，用于后续提取结果
    marker = aici.Label()

    # 循环 5 次，强制生成 "数字." 和 "车辆名称\n"
    for i in range(1, 6):
      await aici.FixedTokens(f"{i}.")
      await aici.gen_text(stop_at="\n")

    await aici.FixedTokens("\n")

    # 将生成的文本保存到变量
    aici.set_var("result", marker.text_since())

aici.start(main())

运行脚本

在项目根目录下执行以下命令运行控制器脚本：

./aici.sh run list-of-five.py

预期输出示例：

Running with tagged AICI Controller: gh:microsoft/aici/pyctrl
[0]: FIXED 'What are the most popular types of vehicles?\n'
[0]: FIXED '1.'
[0]: GEN ' Cars\n'
...
[Response] What are the most popular types of vehicles?
1. Cars
2. Motorcycles
3. Bicycles
4. Trucks
5. Boats

Storage: {'result': '1. Cars\n2. Motorcycles\n3. Bicycles\n4. Trucks\n5. Boats\n\n'}

通过这种方式，您可以用代码精确控制 LLM 的输出结构，而无需依赖模型自身的指令遵循能力。