随着 OpenWebUI 中的用户、对话、文件和知识库数据不断增长，原先部署在 Azure VM 上的自建 PostgreSQL 带来了越来越多的运维工作，包括数据库补丁、备份、故障恢复、存储监控和安全维护。

为了降低维护成本并提高数据库可靠性，我将 OpenWebUI 的业务数据库从 VM 本地 PostgreSQL 迁移到了 Azure Database for PostgreSQL Flexible Server。

这次迁移采用了：

在线全量迁移 + 数据一致性验证 + 活跃对话增量同步 + 快速切换

全量数据库导出和恢复期间，OpenWebUI 始终保持在线。最终切换仅涉及一次很短的 Docker 容器重建，用户侧基本无感。

本文中的服务器地址、数据库名称、用户名、密码和资源标识均已隐藏或替换为占位符。

迁移背景

OpenWebUI 以 Docker 容器形式运行在 Azure VM 中，最初使用安装在同一台 VM 上的 PostgreSQL。

迁移前的架构如下：

用户
  │
  ▼
Azure VM
  ├── OpenWebUI Docker 容器
  │      └── 连接 VM 宿主机 PostgreSQL
  │
  └── PostgreSQL
         └── 数据保存在 VM 本地磁盘

这种部署方式比较简单，但随着应用逐渐稳定运行，数据库维护也成为了新的负担。

需要自行处理的工作包括：

• PostgreSQL 安全更新和补丁
• 数据库备份及备份轮换
• 数据恢复和恢复演练
• 磁盘容量监控
• 数据库服务监控
• PostgreSQL 版本升级
• 故障处理
• 网络和访问权限管理

对于 OpenWebUI 这样的应用来说，数据库是重要的状态组件，但并不是应用的核心运维目标。因此，将 PostgreSQL 迁移到 Azure 托管服务是一个更合理的选择。

迁移后的架构

迁移后的架构如下：

用户
  │
  ▼
Azure VM
  └── OpenWebUI Docker 容器
          │
          ├── Private Endpoint
          │       └── Azure Database for PostgreSQL
          │
          └── 宿主机持久化目录
                  ├── uploads
                  ├── vector_db
                  └── cache

最终实现了：

• OpenWebUI 使用 Azure 托管 PostgreSQL
• 数据库通过 Private Endpoint 私网访问
• 数据库连接启用 TLS
• PostgreSQL 不再占用 VM 本地端口和磁盘
• OpenWebUI 上传文件和向量数据实现持久化挂载
• Azure 自动执行数据库备份
• VM 上只保留 PostgreSQL 客户端，用于日常管理 Azure 数据库

为什么选择 Azure Database for PostgreSQL

1. 降低数据库运维成本

Azure Database for PostgreSQL Flexible Server 是一项托管数据库服务。

与 VM 自建 PostgreSQL 相比，Azure 可以帮助处理大量底层工作，例如：

• 数据库基础设施维护
• 自动备份
• 事务日志备份
• 时间点恢复
• 监控指标采集
• 存储管理
• 计划性维护
• 可选高可用
• 可选只读副本

迁移完成后，VM 只需要负责运行 OpenWebUI，数据库生命周期则交给 Azure 管理。

2. 自动备份和时间点恢复

Azure PostgreSQL 提供内置自动备份，并持续备份事务日志，支持时间点恢复（Point-in-Time Restore，PITR）。

当前环境配置了自动备份保留策略。发生误操作时，可以在保留期内创建一台恢复到指定时间点的新服务器。

与自行编写 pg_dump 和 Cron 脚本相比，Azure 托管备份具有以下优势：

• 不需要维护备份脚本
• 不需要手动轮换备份文件
• 不会占用 VM 本地磁盘
• 可以恢复到保留期内的特定时间
• 备份操作由平台统一管理

需要注意的是，Azure 内置备份主要用于平台恢复，不等同于可随意下载的逻辑备份文件。

如果有以下需求，仍建议额外定期执行 pg_dump：

• 长期离线归档
• 跨平台恢复
• 数据审计
• 跨订阅或跨云迁移
• 保留期超过平台备份策略

3. 使用 Private Endpoint 私网访问

本次迁移没有将 PostgreSQL 直接暴露到公网，而是为 Azure PostgreSQL 配置了 Private Endpoint。

OpenWebUI 访问数据库时，数据库域名通过 Private DNS 解析到 VNet 中的私有 IP：

Azure PostgreSQL FQDN
        ↓
Private DNS
        ↓
Private Endpoint 私有 IP

从 OpenWebUI 容器内部进行了两层验证：

1. DNS 是否解析到私有地址
2. TCP 5432 是否可以通过私网访问

示例：

docker exec -i open-webui python3 - <<'PY'
import socket

host = "<AZURE_POSTGRESQL_PRIVATE_FQDN>"
port = 5432

addresses = sorted({
    item[4][0]
    for item in socket.getaddrinfo(
        host,
        port,
        type=socket.SOCK_STREAM
    )
})

print("Resolved addresses:", addresses)

with socket.create_connection((host, port), timeout=5) as sock:
    print("TCP connection: OK")
    print("Connected peer:", sock.getpeername())
PY

数据库安全性并不只是来自 Private Endpoint，而是来自以下措施的组合：

• Private Endpoint
• Private DNS
• VNet 隔离
• NSG 和路由控制
• 禁用或限制公网访问
• PostgreSQL 身份认证
• TLS 链路加密
• 最小权限数据库账号

4. 数据库连接启用 TLS

OpenWebUI 的数据库连接串启用了：

sslmode=require

脱敏后的连接串格式如下：

postgresql://<APP_USER>:<PASSWORD>@<AZURE_POSTGRESQL_FQDN>:5432/<APP_DATABASE>?sslmode=require

迁移前还通过 OpenWebUI 使用的 Python 和 SQLAlchemy 环境实际验证了 TLS：

import os
from sqlalchemy import create_engine, text

engine = create_engine(os.environ["DATABASE_URL"])

with engine.connect() as conn:
    ssl_enabled = conn.execute(text("""
        SELECT ssl
        FROM pg_stat_ssl
        WHERE pid = pg_backend_pid()
    """)).scalar_one()

print("TLS enabled:", ssl_enabled)

如果安全要求更高，可以进一步使用：

sslmode=verify-full

这种模式不仅加密连接，还会验证证书和服务器主机名，但需要正确配置 CA 证书，并使用与证书匹配的服务器 FQDN。

5. 更容易扩展可靠性能力

迁移到 Azure PostgreSQL 后，可以根据 OpenWebUI 的使用规模继续配置：

• 计算规格扩缩容
• 存储扩容
• 可用区高可用
• 只读副本
• 慢查询分析
• 数据库连接监控
• CPU、内存和存储告警
• 更长的备份保留期
• 异地恢复策略

这使 OpenWebUI 的数据库层从“单 VM 上的本地服务”升级为独立、可管理的托管数据服务。

迁移目标：让 OpenWebUI 尽量保持在线

传统迁移通常采用以下流程：

停止应用
  ↓
导出数据库
  ↓
恢复目标数据库
  ↓
修改连接配置
  ↓
重新启动应用

这种方式虽然简单，但数据库越大，停机时间越长。

本次迁移采用了不同策略：

在线全量备份
  ↓
在线恢复到 Azure PostgreSQL
  ↓
验证结构、权限和数据
  ↓
同步迁移期间新增的活跃对话
  ↓
快速重建 OpenWebUI 容器

在以下阶段，OpenWebUI 都保持在线：

• 全量 pg_dump
• Azure PostgreSQL 数据恢复
• 表结构验证
• 数据量对比
• Private Endpoint 验证
• TLS 验证
• 增量数据同步

最终只有更换 DATABASE_URL 并重建容器时发生了短暂连接中断。

因此，更准确地说，这是一种：

近零停机、用户侧近乎无感知的 OpenWebUI 数据库迁移方案。

迁移前检查 OpenWebUI

1. 确认 OpenWebUI 使用的数据库类型

首先检查 OpenWebUI 容器环境变量：

docker inspect open-webui \
  --format '{{range .Config.Env}}{{println .}}{{end}}' |
grep -E 'DATABASE_URL|DATA_DIR|WEBUI_SECRET_KEY'

确认 OpenWebUI 已经使用 PostgreSQL，而不是默认 SQLite：

DATABASE_URL=postgresql://<LOCAL_USER>:***@<LOCAL_HOST>:5432/<LOCAL_DATABASE>

由于源端和目标端都是 PostgreSQL，因此可以直接使用：

pg_dump → pg_restore

不需要使用 SQLite 到 PostgreSQL 的转换工具。

2. 检查源数据库

检查 PostgreSQL 版本和数据库大小：

sudo -u postgres psql \
  -d <LOCAL_DATABASE> \
  -c "
SELECT
  current_database(),
  current_setting('server_version'),
  pg_size_pretty(
    pg_database_size(current_database())
  );
"

同时检查源数据库使用了哪些扩展：

sudo -u postgres psql \
  -d <LOCAL_DATABASE> \
  -c "
SELECT extname, extversion
FROM pg_extension
ORDER BY extname;
"

本次源数据库没有使用额外的第三方扩展，因此降低了跨环境迁移的兼容性风险。

3. 检查 OpenWebUI 的本地文件

数据库并不是 OpenWebUI 的全部数据。

检查容器挂载后发现，原容器没有配置持久化 volume，而 /app/backend/data 中已经存在大量数据：

/app/backend/data
├── cache
├── uploads
└── vector_db

这些内容包括：

• 用户上传文件
• 向量数据库
• 缓存
• 其他应用本地状态

它们不会进入 PostgreSQL 的 pg_dump，因此必须单独处理。

这也是本次迁移中一个非常重要的发现：

迁移 OpenWebUI 的 PostgreSQL，并不等于迁移了 OpenWebUI 的全部数据。

准备 Azure PostgreSQL

1. 创建独立应用账号

不建议让 OpenWebUI 长期使用 Azure PostgreSQL 管理员账号。

在目标服务器中创建专用角色：

CREATE ROLE <APP_USER> LOGIN;

通过 psql 交互方式设置密码，可以避免密码出现在 Shell 历史记录中：

\password <APP_USER>

然后创建目标数据库：

CREATE DATABASE <APP_DATABASE>
OWNER <APP_USER>;

2. 验证应用账号

psql \
  "host=<AZURE_POSTGRESQL_FQDN> \
   port=5432 \
   dbname=<APP_DATABASE> \
   user=<APP_USER> \
   sslmode=require" \
  -W \
  -c "SELECT current_user, current_database();"

同时确认目标数据库为空：

SELECT count(*)
FROM information_schema.tables
WHERE table_schema = 'public'
  AND table_type = 'BASE TABLE';

3. 处理 public schema 权限

第一次测试恢复时遇到了：

ERROR: permission denied for schema public

原因是应用账号虽然可以连接数据库，但没有在 public schema 中创建对象的权限。

使用管理员账号连接目标数据库后执行：

ALTER SCHEMA public OWNER TO <APP_USER>;

GRANT USAGE, CREATE
ON SCHEMA public
TO <APP_USER>;

这个问题说明，仅验证账号“能否登录”还不够，还需要确认该账号能否：

• 创建表
• 创建索引
• 创建序列
• 创建约束
• 执行 OpenWebUI 的 Alembic 数据库迁移

在线执行全量数据库迁移

1. 在线导出 OpenWebUI 数据库

PostgreSQL 的 pg_dump 会基于一致性事务快照导出数据，因此可以在 OpenWebUI 继续运行时执行。

sudo -u postgres pg_dump \
  --dbname=<LOCAL_DATABASE> \
  --format=custom \
  --no-owner \
  --no-acl \
  --file=/tmp/openwebui-pre-migration.dump

参数含义：

• --format=custom：使用 PostgreSQL 自定义归档格式
• --no-owner：不恢复源端对象 owner
• --no-acl：不恢复源端权限
• --file：指定备份文件

检查归档是否有效：

pg_restore \
  --list \
  /tmp/openwebui-pre-migration.dump |
head -30

自定义格式会保留：

• 表结构
• 表数据
• 主键
• 唯一约束
• 索引
• 外键
• 序列
• Alembic 迁移版本

2. 恢复到 Azure PostgreSQL

pg_restore \
  --host=<AZURE_POSTGRESQL_FQDN> \
  --port=5432 \
  --username=<APP_USER> \
  --dbname=<APP_DATABASE> \
  --no-owner \
  --no-acl \
  --exit-on-error \
  --verbose \
  /tmp/openwebui-pre-migration.dump

使用：

--exit-on-error

可以确保遇到恢复错误时立即停止，避免忽略关键问题。

恢复成功后更新统计信息：

psql \
  "host=<AZURE_POSTGRESQL_FQDN> \
   port=5432 \
   dbname=<APP_DATABASE> \
   user=<APP_USER> \
   sslmode=require" \
  -W \
  -c "ANALYZE;"

对比源端与目标端数据

恢复完成后，需要对 OpenWebUI 的核心表进行对比。

示例查询：

SELECT
  (SELECT count(*) FROM "user") AS users,
  (SELECT count(*) FROM chat) AS chats,
  (SELECT count(*) FROM chat_message) AS chat_messages,
  (SELECT count(*) FROM file) AS files,
  (SELECT count(*) FROM knowledge) AS knowledge,
  (
    SELECT count(*)
    FROM information_schema.tables
    WHERE table_schema = 'public'
      AND table_type = 'BASE TABLE'
  ) AS tables;

重点检查：

• 用户数量
• 对话数量
• 消息数量
• 文件记录数量
• 知识库数量
• 业务表数量
• Alembic 版本
• 表 owner
• 序列状态

对比时发现，目标端的对话消息比源端少了少量记录。

这并不是恢复失败，而是因为：

在全量备份和恢复过程中，OpenWebUI 仍然在线，当前迁移操作的对话还在不断产生新消息。

因此，下一步需要同步全量快照之后新增的数据。

同步迁移期间新增的活跃对话

本次迁移期间，主要只有当前操作对话仍在更新，因此没有再次恢复整个数据库，而是只同步当前活跃对话。

涉及两张表：

chat
chat_message

1. 找到最近更新的对话

SELECT
  c.id,
  c.title,
  to_timestamp(c.updated_at) AS updated_at,
  count(cm.id) AS message_count
FROM chat c
LEFT JOIN chat_message cm
  ON cm.chat_id = c.id
GROUP BY
  c.id,
  c.title,
  c.updated_at
ORDER BY c.updated_at DESC
LIMIT 5;

确定活跃对话后，后续脚本通过环境变量或参数接收对话 ID，而不是将其直接写入公开文档：

CHAT_ID="<ACTIVE_CHAT_ID>"

2. 使用一致性快照导出对话数据

为了保证 chat 和 chat_message 来自同一个时间点，使用只读、可重复读事务：

BEGIN TRANSACTION
ISOLATION LEVEL REPEATABLE READ
READ ONLY;

然后在同一事务中导出：

\copy (
  SELECT *
  FROM chat
  WHERE id = '<ACTIVE_CHAT_ID>'
) TO '/tmp/chat.csv'
WITH (FORMAT CSV);

\copy (
  SELECT *
  FROM chat_message
  WHERE chat_id = '<ACTIVE_CHAT_ID>'
  ORDER BY created_at, id
) TO '/tmp/chat-messages.csv'
WITH (FORMAT CSV);

最后提交：

COMMIT;

需要注意：psql 的 \copy 是客户端元命令，复杂字段列表最好写在同一行，否则可能出现：

\copy: parse error at end of line

3. 在 Azure 中使用临时表和 UPSERT

目标端创建临时 staging 表：

CREATE TEMP TABLE stage_chat
(LIKE public.chat INCLUDING DEFAULTS);

CREATE TEMP TABLE stage_chat_message
(LIKE public.chat_message INCLUDING DEFAULTS);

将 CSV 导入临时表后，对 chat 主记录执行 UPSERT：

INSERT INTO public.chat (...)
SELECT ...
FROM stage_chat
ON CONFLICT (id) DO UPDATE SET
  title              = EXCLUDED.title,
  updated_at         = EXCLUDED.updated_at,
  chat               = EXCLUDED.chat,
  meta               = EXCLUDED.meta,
  current_message_id = EXCLUDED.current_message_id;

对消息表执行类似操作：

INSERT INTO public.chat_message (...)
SELECT ...
FROM stage_chat_message
ON CONFLICT (id) DO UPDATE SET
  content         = EXCLUDED.content,
  output          = EXCLUDED.output,
  status_history  = EXCLUDED.status_history,
  error           = EXCLUDED.error,
  usage           = EXCLUDED.usage,
  done            = EXCLUDED.done,
  updated_at      = EXCLUDED.updated_at,
  context_summary = EXCLUDED.context_summary;

为了让 Azure 中该对话的消息集合与源快照完全一致，还会删除目标端多余记录：

DELETE FROM public.chat_message target
WHERE target.chat_id = '<ACTIVE_CHAT_ID>'
  AND NOT EXISTS (
    SELECT 1
    FROM stage_chat_message staged
    WHERE staged.id = target.id
  );

整个导入和 UPSERT 过程放在一个事务中执行：

BEGIN;

-- 创建临时表
-- 导入数据
-- UPSERT
-- 清理多余记录

COMMIT;

如果任何步骤失败，事务会自动回滚，不会留下部分同步数据。

最终快速切换 OpenWebUI

完成在线全量迁移后，最终操作为：

最后同步一次当前活跃对话
              ↓
重建 OpenWebUI 容器
              ↓
新容器连接 Azure PostgreSQL

示例：

./sync-active-chat-to-azure.sh && \
docker compose \
  -f run-with-azure-pg.yml \
  up -d --force-recreate

完整数据库已经提前迁移并验证，因此最终阶段不需要再次等待几百 MB 数据恢复，只需要同步少量增量记录并快速重建容器。

这将切换窗口缩短到了容器启动所需的时间。

安全保存 OpenWebUI 数据库连接串

数据库连接串没有直接写入 Compose 文件，而是放在独立环境文件中：

open-webui-azure-db.env

文件内容形式：

DATABASE_URL=postgresql://<APP_USER>:<URL_ENCODED_PASSWORD>@<AZURE_POSTGRESQL_FQDN>:5432/<APP_DATABASE>?sslmode=require

文件权限设置为：

chmod 600 open-webui-azure-db.env

如果密码包含特殊字符，需要先进行 URL 编码：

python3 - <<'PY'
import getpass
import urllib.parse

password = getpass.getpass("Database password: ")
print(urllib.parse.quote(password, safe=""))
PY

新的 Compose 文件示例：

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:<VERSION>
    container_name: open-webui
    restart: always

    ports:
      - "8080:8080"

    env_file:
      - ./open-webui.env
      - ./open-webui-azure-db.env

    volumes:
      - /opt/open-webui/data:/app/backend/data

持久化 OpenWebUI 本地文件

迁移前，OpenWebUI 的 /app/backend/data 没有挂载到宿主机。

先将数据复制出来：

sudo install \
  -d \
  -m 700 \
  -o "$(id -un)" \
  -g "$(id -gn)" \
  /opt/open-webui/data

docker cp \
  open-webui:/app/backend/data/. \
  /opt/open-webui/data/

在 Compose 中加入：

volumes:
  - /opt/open-webui/data:/app/backend/data

这样，即使未来重建或升级 OpenWebUI 容器，以下内容仍会保留：

• 上传文件
• 向量数据库
• 缓存
• 其他本地应用数据

迁移后验证：

docker inspect open-webui \
  --format '{{range .Mounts}}{{println .Source "->" .Destination "rw=" .RW}}{{end}}'

预期：

/opt/open-webui/data -> /app/backend/data rw=true

迁移后的验证

1. OpenWebUI 健康检查

curl \
  -sS \
  -o /dev/null \
  -w 'HTTP %{http_code}\n' \
  --max-time 10 \
  http://127.0.0.1:8080/health

预期：

HTTP 200

2. 验证 OpenWebUI 当前数据库

为了避免输出密码，只解析连接串中的非敏感部分：

docker exec -i open-webui python3 - <<'PY'
import os
from urllib.parse import urlsplit

u = urlsplit(os.environ["DATABASE_URL"])

print("Database host configured:", bool(u.hostname))
print("Database port:", u.port)
print("TLS required:", "sslmode=require" in u.query)
PY

验证重点：

• Host 已不再指向 VM 本地 PostgreSQL
• 端口为 5432
• 已启用 sslmode=require

3. 检查启动日志

docker logs \
  --since 15m \
  open-webui 2>&1 |
grep -Ei \
  'error|fatal|exception|traceback|permission denied|database|postgres|alembic|ssl|timeout'

正常情况下只会看到类似：

INFO [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO [alembic.runtime.migration] Will assume transactional DDL.

不应出现：

• 数据库连接失败
• 密码认证失败
• TLS 错误
• Schema 权限错误
• Alembic 迁移失败
• Python Traceback

卸载 VM 本地 PostgreSQL

确认 OpenWebUI 已稳定连接 Azure PostgreSQL 后，可以删除 VM 上的本地 PostgreSQL。

首先确认：

• OpenWebUI 健康检查正常
• 数据库连接已切换
• Azure PostgreSQL 中存在最新数据
• 自动备份策略已经启用
• 本地 PostgreSQL 不再有应用连接

停止并删除本地集群：

sudo pg_dropcluster \
  --stop \
  <POSTGRESQL_VERSION> \
  main

卸载 PostgreSQL 服务端：

sudo apt-get purge -y \
  postgresql \
  postgresql-<POSTGRESQL_VERSION> \
  postgresql-contrib

删除遗留数据和配置：

sudo rm -rf \
  /var/lib/postgresql \
  /etc/postgresql \
  /var/log/postgresql

可以继续保留 PostgreSQL 客户端：

postgresql-client
postgresql-client-common

这样仍然可以从 VM 使用 psql 管理 Azure PostgreSQL。

最终检查本地 5432：

if sudo ss -lntp | grep -q ':5432'; then
  sudo ss -lntp | grep ':5432'
else
  echo "No local PostgreSQL listener"
fi

迁移过程中的经验总结

1. 数据库迁移不等于 OpenWebUI 全部数据迁移

OpenWebUI 除了 PostgreSQL，还可能在 /app/backend/data 中保存：

• 上传文件
• 向量数据库
• 缓存
• 本地状态文件

只执行 pg_dump 并不能迁移这些内容。

2. 不要只测试端口连通

nc 成功只能证明 TCP 5432 可达，并不能证明：

• PostgreSQL 用户可以登录
• 密码正确
• TLS 正常
• 数据库权限正确
• OpenWebUI 使用的驱动兼容

应至少完成以下验证：

DNS → TCP → PostgreSQL 登录 → TLS → SQL 查询 → OpenWebUI 实际连接

3. 数据库 owner 不代表一定拥有 schema 创建权限

即使应用用户是数据库 owner，也可能遇到：

permission denied for schema public

迁移前应验证应用账号是否具备：

• USAGE
• CREATE
• 表和序列所有权
• Alembic DDL 权限

4. 在线全量备份后必须处理增量写入

pg_dump 提供的是开始备份时的一致性快照。

备份期间 OpenWebUI 新产生的对话和消息不会自动进入已经完成的 dump。因此在线迁移必须增加以下机制之一：

• 最终停写后重新完整备份
• 逻辑复制
• CDC
• 应用双写
• 按业务对象执行增量同步

本次采用的是“全量快照 + 活跃对话 UPSERT”。

5. 不要在迁移时顺便升级 OpenWebUI

本次迁移始终保持 OpenWebUI 镜像版本不变。

如果同时升级应用和迁移数据库，一旦发生问题，很难快速判断原因来自：

• PostgreSQL 版本
• 数据迁移
• Azure 网络
• 数据库权限
• OpenWebUI 版本
• Alembic schema 变化

更稳妥的做法是：

先迁移数据库并稳定运行
          ↓
再单独升级 OpenWebUI

这算不算真正的零停机？

从用户体验看，这次迁移接近零停机：

• 在线完成全量备份
• 在线恢复目标数据库
• 在线完成数据验证
• 在线同步活跃对话
• 仅在最后重建了一次 OpenWebUI 容器

但如果采用严格工程定义，真正的零停机还需要满足：

• 任意时刻都能接受新连接
• 最后时刻写入绝不丢失
• 没有单实例容器重启窗口
• 客户端连接完全不中断
• 具备自动流量切换能力

更大规模的 OpenWebUI 部署可以考虑：

• PostgreSQL 逻辑复制
• Azure Database Migration Service
• CDC 增量迁移
• 应用双写
• 蓝绿部署
• 多个 OpenWebUI 实例
• 反向代理健康检查
• 连接排空和流量切换

对于单 VM、单 OpenWebUI 容器和中小规模数据库，本次采用的方案在复杂度、风险和停机时间之间取得了较好的平衡。

迁移后的日常运维

启动 OpenWebUI：

docker compose \
  -f run-with-azure-pg.yml \
  up -d

查看状态：

docker compose \
  -f run-with-azure-pg.yml \
  ps

查看日志：

docker compose \
  -f run-with-azure-pg.yml \
  logs -f --tail=200

健康检查：

curl \
  -sS \
  -o /dev/null \
  -w 'HTTP %{http_code}\n' \
  http://127.0.0.1:8080/health

日常还应重点监控 Azure PostgreSQL 的：

• CPU 使用率
• 内存使用情况
• 存储空间
• 活跃连接数
• 失败连接数
• 查询延迟
• 自动备份状态
• 维护事件
• Private Endpoint 状态

总结

这次迁移将 OpenWebUI 的数据库从 Azure VM 自建 PostgreSQL 平滑迁移到了 Azure Database for PostgreSQL Flexible Server。

最终实现了：

• OpenWebUI 数据库由 Azure 托管
• 通过 Private Endpoint 私网访问
• 数据库连接启用 TLS
• 自动备份和时间点恢复
• OpenWebUI 本地文件持久化
• VM 本地 PostgreSQL 完全下线
• 本地 5432 端口关闭
• 全量迁移期间应用持续在线
• 最终切换对用户影响极低

本次最关键的经验是：

对 OpenWebUI 进行低停机数据库迁移，不应只关注 pg_dump 和 pg_restore，还必须同时考虑增量写入、Private Endpoint、TLS、数据库权限、Alembic 迁移以及 /app/backend/data 中的本地文件。

通过“在线全量迁移、目标端预验证、活跃数据增量同步、快速容器切换”，可以在不引入复杂 CDC 平台的情况下，将中小规模 OpenWebUI 平滑迁移到 Azure 托管 PostgreSQL。

在大模型应用快速落地的过程中，推理服务的工程化能力往往比模型本身更复杂：模型调度、路由策略、限流、灰度发布、网关治理等问题，都需要真实的推理接口进行验证。然而，大模型推理依赖 GPU 和高成本算力资源，使得开发和测试门槛居高不下。

如果你希望在没有 GPU 或资源受限的环境中验证推理架构设计，那么这个工具值得关注：

llm-d-inference-sim GitHub 项目

本文将系统介绍这个工具的能力、设计思路，以及它在实际工程中的应用价值。

工具定位：为推理工程而生的“模拟器”

llm-d-inference-sim 是一个专门用于模拟大模型推理服务的工具，其核心能力包括：

• 提供与真实 LLM 推理服务一致的接口（如 OpenAI-style API）
• 接收推理请求（prompt / messages）
• 按配置生成“模拟响应”
• 支持多实例、多模型模拟部署

简单来说，它并不真正执行模型推理，而是：

模拟“推理服务行为”，而非“推理计算本身”

为什么需要推理模拟？

在真实项目中，我们经常遇到以下问题：

1. 推理资源昂贵

• GPU 成本高（A100 / H100）
• 推理服务部署复杂（vLLM / TensorRT-LLM / SGLang）
• 测试环境难以复刻生产规模

2. 工程验证依赖真实服务

很多关键能力必须依赖推理接口验证，例如：

• API 网关路由策略（Envoy / Istio）
• 多模型调度与 fallback 机制
• embedding + intent routing
• 限流 / 熔断 / 超时控制
• 灰度发布与 A/B testing

但这些能力并不依赖模型“正确性”，只依赖：

“是否有一个行为类似 LLM 的服务存在”

llm-d-inference-sim 的核心价值

1. 零 GPU 依赖

开发者可以在以下环境直接使用：

• 本地 MacBook
• CI/CD 环境
• Kubernetes 测试集群
• 云主机（无 GPU）

无需部署任何真实模型。

2. 高度可控的响应模拟

可以模拟：

• 固定响应（用于稳定测试）
• 延迟（模拟推理耗时）
• Token 生成节奏（Streaming）
• 错误返回（测试容错）

这使它非常适合：

压测、容错测试、链路验证

3. 支持多模型实例

你可以快速部署多个“模拟模型”：

• gpt-4 模拟服务
• embedding 模型模拟
• 不同延迟 / 不同性能 profile

用于验证：

• 多模型路由策略
• 智能网关（AI Gateway）
• fallback 逻辑

4. 与真实 API 兼容

接口风格通常兼容：

• OpenAI API（/v1/chat/completions）
• streaming 输出

这意味着：

可以无缝替换真实模型服务

典型使用场景

场景 1：AI 网关 / 服务网格验证

例如使用 Envoy / Istio 构建 AI Gateway：

• 基于路径或 header 路由不同模型
• embedding-based routing
• Canary 发布

问题：没有真实模型怎么办？

使用 llm-d-inference-sim 模拟多个模型后端，即可验证完整链路。

场景 2：多模型调度系统开发

在做类似以下系统时：

• vLLM-aware scheduler
• KV Cache aware routing
• 模型负载均衡

你需要：

• 多个模型 endpoint
• 不同响应延迟
• 可控行为

模拟器可以快速构造这些环境。

场景 3：CI/CD 自动化测试

真实模型服务难以接入 CI：

• 成本高
• 不稳定
• 启动慢

使用模拟器：

• 启动快速
• 行为可预测
• 支持 mock response

非常适合集成测试（integration test）

场景 4：产品演示 / Demo 环境

在售前或内部 Demo 中：

• 不需要真实模型
• 只需要“看起来能跑”

使用模拟器可以：

• 快速部署多个模型服务
• 构造稳定演示环境
• 避免 GPU 成本

工作原理简析

llm-d-inference-sim 的设计可以理解为：

请求流程

1. 接收 HTTP 请求（如 /v1/chat/completions）
2. 解析输入（prompt/messages）
3. 根据配置规则生成响应
4. 返回 JSON 或 streaming 输出

模拟能力通常包括

• Response 模板

  • 固定文本
  • 参数化生成

• Latency 注入

  • 模拟推理耗时（如 200ms / 2s）

• Streaming

  • 分块返回 token
  • 模拟真实 LLM 输出节奏

• 错误注入

  • 500 / timeout
  • 测试重试机制

与真实推理服务的关系

模拟器 ≠ 替代模型，而是补齐工程验证环节

最佳实践建议

1. 与网关结合使用

推荐组合：

• Envoy / Istio
• AI Gateway
• llm-d-inference-sim

构建完整推理流量链路

2. 构造多模型拓扑

例如：

• model-a（低延迟）
• model-b（高质量，高延迟）
• model-fallback

验证智能路由策略

3. 注入异常场景

主动模拟：

• timeout
• 高延迟
• 错误返回

提升系统鲁棒性

4. 用于开发早期阶段

在以下阶段优先使用模拟器：

• 架构设计
• API 设计
• 路由策略验证

等到后期再接入真实模型。

总结

llm-d-inference-sim 解决的是一个被低估但关键的问题：

在没有模型的情况下，如何推进大模型工程化？

它的核心价值不在于“模拟模型”，而在于：

• 降低开发门槛
• 提升验证效率
• 解耦算力与工程

对于正在构建 AI 基础设施（AI Gateway / 推理平台 / 多模型调度系统）的团队来说，这是一个非常实用的工具。

如何在不显式指定模型 ID 的情况下，让系统自动选择最合适的模型？

本文介绍一种工程可落地的方案：

通过 Embedding 模型计算用户意图 → 在网关层进行语义匹配 → 动态路由到最合适的上游模型服务

我们将基于：

• Embedding 模型：Azure OpenAI text-embedding-3-small
• 网关：Envoy
• 核心机制：向量相似度打分 + 策略路由

问题背景与动机

在真实生产环境中，大模型调用通常面临几个挑战：

1. 成本与性能权衡

不同请求应该走不同模型，而不是“一刀切”。

2. 传统做法的局限

常见策略：

• 手动指定 model_id ❌（不智能）
• 基于规则（if/else）❌（不可扩展）
• 基于关键词匹配 ❌（语义不鲁棒）

3. 理想目标

我们希望：

用户只输入 prompt，系统自动理解“意图”，并选择最优模型

这正是 Embedding 可以发挥作用的地方。

核心原理：Embedding 驱动的语义路由

1. Embedding 本质

Embedding 模型（如 text-embedding-3-small）可以将文本映射为高维向量：

"写一段 Python 排序代码"
→ [0.012, -0.98, ..., 0.33]  (1536维向量)

语义相似的文本，其向量距离更近。

2. 路由思路

核心逻辑可以抽象为：

用户请求 → Embedding → 与“意图模板库”计算相似度 → 选择最佳匹配 → 路由模型

3. 意图模板（Intent Prototypes）

我们预先定义一组“意图向量”：

这些文本会提前计算 embedding 并缓存。

4. 相似度计算

常用方法：

• Cosine Similarity（推荐）

similarity = cosine(query_embedding, intent_embedding)

选择最高分：

argmax(similarity_i)

系统架构设计

整体架构如下：

                ┌──────────────┐
                │   Client     │
                └──────┬───────┘
                       │
               ┌───────▼────────┐
               │    Envoy 网关   │
               │   (智能路由层)   │
               └───────┬────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
 ┌──────▼─────┐ ┌──────▼─────┐ ┌──────▼─────┐
 │ GPT-4      │ │ GPT-4o-mini│ │ 专用模型    │
 └────────────┘ └────────────┘ └────────────┘

实现逻辑拆解

1. 请求流程

Step 1：获取用户请求

{
  "input": "帮我写一段 Go 的 HTTP server 示例"
}

Step 2：调用 Embedding API

使用 Azure OpenAI：

POST https://{endpoint}/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-02-15-preview

请求体：

{
  "input": "帮我写一段 Go 的 HTTP server 示例"
}

Step 3：计算相似度

伪代码：

def route(query_embedding):
    best_score = -1
    best_model = None

    for intent in intents:
        score = cosine_similarity(query_embedding, intent.embedding)
        if score > best_score:
            best_score = score
            best_model = intent.model

    return best_model

Step 4：Envoy 动态路由

将结果写入 Header：

x-llm-route: gpt-4

Envoy 根据 Header 路由：

routes:
- match:
    prefix: "/v1/chat"
    headers:
      - name: x-llm-route
        exact_match: gpt-4
  route:
    cluster: gpt4_service

Envoy 网关实现方式

Envoy 本身不直接支持向量计算，因此需要扩展：

方案 1：External Processing（推荐）

Envoy 调用外部服务（ext_proc）：

Envoy → ext_proc 服务 → 返回路由决策 → Envoy 转发

ext_proc 负责：

• 调用 embedding
• 计算相似度
• 返回 header

方案 2：WASM 插件

在 Envoy 内嵌逻辑：

• 优点：低延迟
• 缺点：开发复杂（Rust/CPP）

方案 3：Sidecar Router（简单）

Client → Router Service → Envoy → Model

Router 服务负责所有智能逻辑。

优化策略

1. 向量缓存

避免重复调用 embedding：

cache[input_hash] = embedding

2. 意图分层

避免单层分类过粗：

一级：代码 / 问答 / 写作
二级：语言 / 长度 / 难度

3. 阈值控制

if best_score < threshold:
    fallback_model = "gpt-4"

防止误判。

4. 多模型融合（Ensemble）

可扩展为：

• Top-K 模型候选
• A/B 测试
• 加权路由

5. 成本感知路由

结合：

• token 预算
• 用户等级
• SLA

做策略增强：

if user == "free":
    prefer_small_model()

优势分析

相比规则路由

相比手动指定模型

• 用户体验更好（无需关心模型）
• 自动最优成本
• 支持动态策略

落地建议

1. 初始阶段

• 5~10 个意图模板即可
• 手动标注 + 调优

2. 数据驱动优化

记录：

• 用户请求
• 路由结果
• 用户反馈

持续优化 intent embedding。

3. 与 LLM Router 结合

未来可以升级为：

用小模型 + embedding 混合决策（Hybrid Router）

总结

本文方案的本质是：

用 Embedding 替代规则，用向量相似度驱动模型选择

关键收益：

• 降低成本（智能选择轻量模型）
• 提升效果（复杂任务走强模型）
• 架构解耦（路由逻辑与模型解耦）

在多模型时代，这种“语义驱动的网关”会成为标准架构组件。

2025 年末，微软研究院发布了一个面向 3D 内容创作的开源大模型项目 TRELLIS，并伴随学术论文《Structured 3D Latents for Scalable and Versatile 3D Generation》。该项目通过统一的结构化潜在空间与先进的流模型技术，显著提升了文本/图像到 3D 资产生成的质量与灵活性，同时拓展了 3D 模型的多格式输出与编辑能力，成为当前 3D AI 模型生态中的重要技术之一。

官方 Github 仓库地址：https://github.com/microsoft/TRELLIS

TRELLIS 是什么？——核心概念与架构

TRELLIS 是微软构建的大型 3D 资产生成模型，支持输入文本提示或图像，并输出高质量的三维模型资产。其技术创新点主要包括：

• 统一结构化潜在表示（SLAT）：将三维信息编码为一种可扩展的结构化潜在空间表示，使模型能够以统一方式理解和生成不同表现形式的 3D 结果。
• 整流流（Rectified Flow Transformers）：专为 SLAT 设计的生成骨干网络，通过适应 sparse 表示提升生成效率与质量。
• 大规模训练与预训练模型：模型规模最高达约 20 亿参数，并在包含 50 万多样化三维资产的数据集上训练，具备强泛化能力。

TRELLIS 不仅能生成三维几何，还能捕获复杂纹理与外观信息，使得生成的资产更贴近真实世界中可用的三维内容。

主要功能特性

以下是 TRELLIS 的核心功能模块及技术亮点：

多模态输入能力

TRELLIS 支持以下输入条件：

• 文本提示（Text-to-3D）：通过自然语言描述生成三维资产（提示须清晰准确）。
• 图像条件（Image-to-3D）：根据一张或多张图片生成对应三维模型。

这种多模态输入支持，使 TRELLIS 适用于从概念设计到真实原型的全流程创作。

灵活的输出格式

根据下游需求，TRELLIS 输出包括：

• 辐射场（NeRF/Radiance Fields）：适合渲染与展示
• 3D 高斯表示：一种可渲染密度表示
• 传统网格 Mesh：可导出为标准 3D 文件格式（例如 GLB/OBJ）用于游戏、AR/VR 等应用

这种格式灵活性是模型在实际生产环境中落地的关键能力。

本地三维编辑与变体生成

与早期单一生成模型不同，TRELLIS 能：

• 局部编辑：在已有模型上进行细部修改
• 生成变体：在保持基本结构不变的前提下，创建风格、细节不同的多版本输出

这种能力特别适合迭代式 3D 内容设计。

支持大规模数据集训练与可扩展性

TRELLIS 在包含多种来源（如 Objaverse、ABO 等）的大规模 3D 数据集上进行训练，使其具备：

• 强泛化能力
• 更丰富的几何与纹理表现
• 多任务适配能力

这样的数据基础是其较竞品更具优势的根本原因之一。

与其他竞品对比：优势与提升点

目前市场上其他比较知名的 3D 生成模型（例如 OpenAI Shap-E、或研究型模型如 MeshGen 等）多存在以下局限：

• 有的只能输出单一 3D 表示（如内隐函数或点云）
• 多数不支持本地编辑与多种格式输出
• 在复杂纹理、细节表现上效果有限

相比之下：

TRELLIS 的主要优势包括

1. 结构化潜在表示（SLAT）框架：支持统一的生成与解码机制，同时兼顾几何与纹理细节。
2. 多格式生成输出：与只生成单种数据结构的竞品相比更通用。
3. 本地编辑与变体生成：提升了设计迭代效率。
4. 大规模预训练与更丰富数据集支撑：提升了模型对稀有或复杂对象的生成能力。

总的来说，TRELLIS 更偏向工业级 3D 生成工具，而不只是科研展示或单一生成模型。

部署和使用

目前，微软尚未在 Azure AI Foundry / Microsoft Foundry 中以 Serverless 或托管模型的形式直接提供 TRELLIS。因此，在 Azure 云环境中使用 TRELLIS 的最可行、也是最稳定的方式，是基于 Azure GPU 虚拟机（VM）进行自托管部署。

这种方式具备以下优势：

• 完全控制模型版本与推理流程
• 支持大显存 GPU，适合 3D 模型生成场景
• 可与企业现有 Azure 网络、安全、存储体系无缝集成

1. Azure GPU VM 规格选型建议

TRELLIS 属于显存与算力敏感型 3D 生成模型，对 GPU 资源要求较高，推荐如下规格：

推荐 VM 系列

• Standard_NC A100 v4（A100 80GB，首选）
• Standard_NC A100 v5（A100 80GB，新一代）
• Standard_ND H100 v5（H100，若需要更高吞吐）

实践建议：

• 推理 / Demo：单卡 A100 80GB 即可
• 高分辨率 / 批量生成 / 编辑任务：建议单机多卡或更高规格

2. 操作系统与基础环境

推荐环境组合如下：

• OS：Ubuntu 20.04 / 22.04 LTS
• CUDA：与 VM 驱动匹配的官方版本
• Python：3.8 或以上
• PyTorch：官方 CUDA 版本

Azure Marketplace 中可直接选择 CUDA + NVIDIA Driver 预装镜像，可显著降低环境准备成本。

3. TRELLIS 安装与依赖配置

拉取代码

git clone --recurse-submodules https://github.com/microsoft/TRELLIS.git
cd TRELLIS

创建独立 Python 环境并安装依赖

官方已提供自动化脚本：

./setup.sh --new-env --basic

如需支持训练、编辑或高级功能，可根据官方说明启用对应参数。

4. 基于 Azure VM 的推理运行方式

方式一：命令行推理（适合批量任务）

文本或图像驱动生成 3D 模型：

python example_text.py \
  --prompt "a futuristic electric motorcycle" \
  --output_dir outputs/

或多图像条件输入：

python example_multi_image.py \
  --input_images images/ \
  --output_dir outputs/

生成结果可直接导出为 Mesh / Radiance Field 等格式，用于后续渲染或工具链集成。

方式二：Gradio Web UI（推荐用于演示与验证）

TRELLIS 官方提供基于 Gradio 的 Web Demo，适合：

• 团队内部体验
• 产品验证
• 算法效果对比

python app.py

然后通过 Azure VM 公网 IP 或内网负载均衡访问 Web UI。

5. Azure 上的工程化部署建议

为了更好地在 Azure 上长期运行 TRELLIS，建议采用以下架构实践：

存储解耦

• 模型权重：Azure Blob Storage
• 生成结果：Blob / Azure Files
• 日志与元数据：Azure Monitor / Log Analytics

服务化封装

• 使用 FastAPI / Flask 将 TRELLIS 推理封装为 HTTP API
• GPU VM 作为推理节点
• 前端或工作流通过 REST 调用

安全与网络

• VM 置于 VNet 内
• Web UI / API 通过 Application Gateway 或内部访问
• 支持私有部署，满足企业安全要求

总结与展望

微软 TRELLIS 代表了当前 3D AI 生成技术的重要进步，它在生成质量、格式多样性与本地编辑能力方面具备显著优势。对于希望自动化 3D 内容创建的开发者与设计者而言，它是一个有实力的开源方案。部署方面，虽然目前官方尚未将其作为 Foundry 的 serverless 模型，但可通过 Azure 的常规模型部署管道与 GPU 计算能力在云端高效运行 TRELLIS 推理与自定义训练。

本文将从架构层面系统梳理 LLM 的主流技术路径，并从应用视角分析其优劣及适配场景，为研发与业务团队提供技术选型参考。同时也希望可以为初学者们打开迈入大模型世界的一条门缝！

大语言模型的主流架构体系

目前的 LLM 架构，大概可以分为这么几类：

1. 传统 Transformer（Dense Transformer）
2. Mixture-of-Experts（MoE）架构
3. 多模态扩展架构（Vision-Language / Audio-Language）
4. 检索增强生成（RAG）与混合推理架构
5. 基于代理（Agentic）架构的系统级 LLM
6. 超大规模分布式训练架构（例如 Parameter Server / Fully Sharded）

下面逐一展开。

传统 Transformer：主流 LLM 的基础架构

Dense Transformer 是绝大多数 LLM 的基座，包括 GPT 系列、LLaMA、Mistral、Qwen 等。

架构

简单来说，就是“大力出奇迹”：

• 所有 token 通过全连接注意力进行计算；
• 全部参数在每次前向推理中都会被激活；
• 结构相对规则，训练稳定；
• 模型规模靠堆叠层数与扩大 hidden size 线性提升。

优势

• 推理路径稳定、可预测；
• 训练过程成熟，生态支持丰富；
• 对所有任务通用，不需要额外路由机制。

局限

• 参数规模大时推理成本高（全部参数激活）；
• 扩展模型能力的成本几乎与参数规模线性相关。

应用场景

Dense 模型依然是绝大多数企业首次采用 LLM 时的首选。

Mixture-of-Experts（MoE）：高效扩展能力的关键技术

MoE 是当前最重要的新架构之一，代表模型包括：

• Google Switch Transformer
• DeepSeek-V2/V3
• Mixtral 系列
• GPT-4 技术论文暗示其有 MoE 结构成分

架构

MoE 不再让所有参数参与每次计算，而是通过路由（Routing）机制让每个 token 只激活若干专家层（Expert）。

举个例子，一个 300B 参数的庞然大物，实际每次推理可能只动用了 30B 的参数。

优势

• 训练扩展性极强：参数规模可以以更低成本提升到数千亿甚至上万亿。
• 推理成本显著降低：激活专家减少推理 FLOPs。
• 擅长复杂推理与多任务能力。

局限

• 路由训练复杂，稳定性需求更高；
• 推理并行规模更大，对系统工程要求高；
• 不适合极端低延迟场景，因为专家调度带来额外开销。

应用场景

MoE 已成为大型商业 LLM 的主流趋势。

多模态 LLM 架构：模型能力向感知延伸

代表模型：GPT-4o、Gemini、Qwen-VL、LLaVA、Yi-VL

架构

多模态 LLM 通过在 Transformer 基座上引入额外编码器，将视觉、音频、视频等信号映射为 token 表示。

典型结构通常包含：

• 视觉编码器（Vision Encoder，比如 ViT）
• 投影层（Projection Layer）
• 统一的 Transformer
• 多模态注意力机制

优势

• 输入能力扩展显著：图像、音频、视频、文档统合处理；
• 极适合作为通用 AI Agent 的感知模块。

局限

• 成本比纯文本 LLM 更高；
• 多模态数据构建成本大；
• 输出的稳定性与高保真图像/视频理解仍有上限。

应用场景

随着 GPT-4o 全模态输入的普及，多模态 LLM 已成为企业 AI 转型的必备能力层。

RAG + LLM 混合架构：以知识增强为核心的系统形态

RAG（Retrieval-Augmented Generation）通过将外部知识库融合到推理中解决 LLM 本身无法持久更新和存储大量事实的问题。

架构

由三个核心组件构成：

• 向量数据库（Retriever）
• 文档预处理管线（Chunking, Indexing）
• 核心 LLM（Generator）

优势

• 模型无需重新训练即可持续更新知识；
• 显著增强长尾知识与事实性能力；
• 数据可控，便于企业级治理。

局限

• 依赖检索质量；
• 对 prompt 工程与 pipeline 工程化要求高；
• 多跳检索在 latency 上存在开销。

应用场景

RAG 是企业级 LLM 落地中最常见的架构。

基于代理的架构：基于智能体的系统级 LLM 架构

代表：AutoGPT、GPT-o1、GPT-o3、DeepSeek-R1、自主推理 Agent Framework

随着模型具备规划（Planning）、执行（Acting）和反思（Reflection）能力，Agent 架构正在成为应用层主流。

架构

• 多工具整合（Tool Use）
• 工作流管理
• 多轮子任务规划
• Memory 与外部状态管理

优势

• 可执行复杂任务链；
• 强化模型可控性；
• 工具能力扩展模型本身的局限。

局限

• 系统复杂度显著增加；
• 可靠性、可追踪性和可验证性要求高；
• 调度能力直接影响实际效果。

应用场景

Agent 架构代表了 LLM 应用的未来方向。

分布式训练架构：支撑万亿参数模型的底层工程

这类方案通常没有特定的架构模型，依照不同的需求，技术厂商会演进出各类方案，比如：

• ZeRO / FSDP（Fully Sharded Data Parallel）
• Megatron-LM（Tensor / Pipeline 并行）
• DeepSpeed
• Colossal-AI
• Parameter Server（SageMaker、Ray、DeepSeek 自研）

优势

• 高效训练超大模型；
• 利用 GPU 集群最大化吞吐；
• 优化显存占用。

局限

• 工程复杂度极高；
• 部署成本昂贵；
• 对 GPU 集群架构高度依赖。

应用场景

主要适用于自研大模型或千卡级 GPU 训练任务的企业或科研团队。

各架构侧重点及优势对比

以下为一张综合对比表：

如何选择适合的 LLM 架构？

基于上述介绍的 LLM 架构，我们初步了解了大语言模型本身的架构以及叠加一些应用场景的方案架构，而在 LLM 结合各个行业的真实应用场景中，架构远远不止这些，结合已有的计算机系统架构，LLM 的架构也在不断进化和丰富中，下面简单根据应用需求，推荐如下路径：

目标是开发一个企业级问答系统

Dense Transformer + 强化 RAG：可靠、易控、低成本、可持续更新。

目标是打造一个全能基础大模型系统

MoE 是优选：性能与性价比兼得。

目标是构建文档/图像/视频 AI 系统

多模态 LLM：例如 GPT-4o、Qwen-VL、Gemini。

需要自动化任务执行

基于代理的架构：模型本身不需要特别大，但需要良好的工具接口和规划能力。

需要训练和运行自研模型

FSDP / Megatron / PS-based 分布式架构，这类需求其实可选范围非常广，由于是训推整体方案，只要沿用市面成型的一体方案即可，不需要花大量时间在训练和推理框架之间做兼容。

总结

大语言模型架构的演进已经进入百花齐放阶段。Dense 模型提供稳定基座，MoE 架构带来成本与能力的突破，多模态扩展了 AI 的感知边界，而 RAG 与 Agent 架构将 LLM 推向真正可控、可执行的智能体时代。

对企业而言，选对架构比盲目追求“更大模型”更重要。依据实际需求、工程能力和预算进行架构选择，既能优化效果，也能确保长期可维护性。

这篇文章将全面介绍什么是 KV-Cache、它如何工作、为什么它能极大提升推理效率、它对行业带来了什么影响，以及在实际使用中的最佳实践。

KV-Cache 是什么？

首先，其工作原理架构图如下：

理解起来非常简单，单其中细节结合复杂度计算还是略有抽象。

KV-Cache，全称 Key-Value Cache，是在 LLM 推理过程中对 Transformer 解码器中自注意力层（Self-Attention）的中间结果进行缓存的一种方法。

Transformer 的自回归生成方式决定了： 每生成一个新 token，就需要重新计算它与全部历史 token 的注意力关系。

如果每次都把过去所有 token 的 Key 和 Value 重新计算一遍，其计算量是：

推理时间复杂度：O(n²) （n 为上下文长度）

为了避免重复计算，KV-Cache 会在每步生成 token 时，将计算后的 Key（K） 和 Value（V） 保存下来，这样之后再生成下一步 token 时就能直接引用过去的 Key/Value，而无需重新计算历史部分。

这让时间复杂度大幅下降为：

推理时间复杂度：O(n)

所以简单总结一下，KV-Cache 是在自回归解码中缓存历史 token 的 Key/Value，让后续生成直接复用过去的注意力结果，从而把时间复杂度从 O(n²) 降到 O(n)，节省的成本非常巨大。

KV-Cache 是如何工作的？

以当前主流的解码流程为例，我们以是否使用 KV-Cache 来做一个简单的对比。

如果没有 KV-Cache

每次生成新 token 时需要做：

1. 重新对全部历史序列做 embedding
2. 通过所有 Transformer 层重新计算 K/V
3. 根据新 token 与整个序列做自注意力
4. 得到新 token 并输出

具体流程图示如下：

使用 KV-Cache

第一次推理（prefill 阶段）：

1. 对所有提示词（prompt tokens）进行计算
2. 计算所有 K/V，并将它们保存在 KV 缓存中

之后的每一步（decode 阶段）：

1. 只计算当前新 token 的 K/V
2. 与缓存中的 K/V 做注意力，得到结果
3. 写回缓存

这样，每生成一个 token 的计算量从全序列规模 → 近似常数开销，越长的上下文收益越大。

其流程图示如下：

KV-Cache 带来了什么影响？

推理速度提升数十倍

对长上下文模型（8k / 32k / 128k tokens）尤其明显。

例如对 32k token 的上下文，如果没有 KV-Cache：

• 每生成一个 token 需要遍历 32k 历史序列
• 整体是 重复 32k 次的巨量工作

有了 KV-Cache：

• 历史部分只算一次
• 单步 decode 的开销变成固定量（几百维 KV 与注意力点积）

通常加速比可达到：

10 倍至 100 倍不等 （取决于提示词长度、模型大小、硬件）

推理成本大幅降低

大模型推理的成本主要由这几个部分构成：

• 算力（矩阵乘法）
• 显存占用
• 带宽

KV-Cache 能大幅降低重复算力，因此成本成比例下降。

这就是为什么：

• OpenAI、Anthropic、Meta、Mistral
• 各大云推理服务
• 所有开源推理框架

都把 KV-Cache 作为默认推理方式。

但是显存占用会变高

KV 是每一层每个 token 的结果，因此缓存本身需要巨大的显存。

例如： Llama-3 70B 模型，64K context，对 1 token 的 KV 占用约 1.5KB。

那么 64K token 就是：约 96MB × 80 层 ≈ 7.6GB 的 KV-cache

当你看到推理卡 80GB 显存不够时，很大概率是因为 KV 满了，而不是模型权重太大。

影响了模型的架构设计与行业走向

KV-Cache 的重要性高到：模型架构都围绕它做优化。

包括：

• Mistral 的滑动窗口注意力（SWA）
• Meta 的 Grouped Query Attention（GQA）
• DeepSeek 的 Multi-head Latent Attention（MLA）
• Google 的 Multi-Query Attention（MQA）

这些技术主要目的之一就是：

降低 KV-Cache 的显存占用

因为 Q 数少 → KV 也变少 → 显存压力更低。

所以 KV-Cache 不只是一个技术点，而是影响模型架构的重要因素。

KV-Cache 的性能关键因素

不同 Attention 架构带来的 KV 大小差异

Prefill 和 Decode 性能壁垒不同

• Prefill 阶段：算 K/V 很耗算力，需要好 GPU。
• Decode 阶段：显存带宽优先，因为每步生成通常 batch 很小。

这也影响推理框架的优化策略。

KV-Cache 的布局与管理

例如：

• PagedAttention（vLLM 的核心技术）
• Block-sparse KV 管理（TensorRT-LLM）
• 动态缓存分配（llama.cpp）
• 连续 vs 分块 KV 内存

优秀的分配策略可以极大减少 fragmentation 和显存浪费。

KV-Cache 的最佳实践

尽量减少上下文长度

上下文越长 → KV 越大 → 推理越慢、越贵。

如果业务允许：

• 使用 RAG 把长文档拆分
• 使用压缩模型（compressor）
• 使用短指令模板
• 引导模型减少“废话”输出

选择合适的 Attention 架构

如果你在自定义模型、微调或部署模型：

• 需要高效推理 → 优选 MQA / GQA / MLA
• 需要兼容许多任务 → MHA 仍然最稳定

使用专业推理框架

优先使用：

• vLLM（商业与开源界第一推理框架）
• TensorRT-LLM（NVIDIA 官方）
• llm-d（中小型企业的极高性价比框架）
• OpenAI Triton 引擎（内部使用）

它们都在 KV-Cache 管理上有深度优化。

多卡推理时注意 KV 分布问题

KV 会引发：

• 多卡同步开销
• all-reduce 带宽瓶颈

部分框架提供：

• KV sharding
• pipeline parallelism
• block-sparse KV sharing

合理设置可显著提升吞吐量。

批处理策略影响巨大

适配 KV-Cache 的批处理策略包括：

• continuous batching
• block scheduling
• prompt+decode 混合 batch

正确 batching 通常带来 >10× 吞吐提升。

KV-Cache 的未来展望

未来几年，模型推理的发展趋势中，KV-Cache 会继续是核心机制。

我们将看到：

• 更轻量的 KV 结构（更少头、更小维度）
• 更智能的 KV 重用机制
• KV 的跨请求共享（multi-query serving）
• 部分 KV 的 CPU/NVMe offload
• Push-down Attention（降低 GPU 带宽要求）

总之，KV-Cache 将继续驱动推理性能提升，是 LLM 推理领域最重要的基础设施之一。

总结

KV-Cache 并不是一个“可选优化”，而是现代大语言模型推理的 核心基石。 它带来巨大的速度提升，但也带来显存压力，影响模型架构、推理框架设计乃至行业整个技术路线。

理解 KV-Cache，你就理解了：

• 为什么推理这么贵
• 为什么上下文越长模型越慢
• 为什么新一代模型都在改注意力结构
• 为什么推理框架竞争如此激烈

准备工作

在开始之前，你需要：

获取 Azure 订阅

拥有一个 Azure 订阅，如果您不清楚如何获取 Azure 订阅，可以参考之前文章中的注册 Azure 订阅内容进行操作。

创建 Azure AI Foundry

首先进入您的 Azure 订阅中的 AI Foundry，展开左侧 All Resources，找到 Azure AI Foundry，点击 Create 创建一个 Azure AI Foundry：

创建时注意区域选择，由于 Sora 2 模型并未在所有 Azure 区域开放预览，这里建议选择 East US 2 区域：

1. 创建 Azure AI Foundry Project

创建完成后进入您的 Azure AI Foundry 在 All Resources 中找到 Projects，点击 New 创建一个新的 Project：

2. 打开 Azure AI Foundry Protal

创建完成 Project 后，打开您的 Project，点击 Go to Azure AI Foundry protal：

正常情况下 Azure AI Foundry Protal 如下：

3. 启用和部署 Sora 2 模型

又有 Sora 2 模型在本文发布时仍然处于预览状态，所以我们首先需要申请权限，后续开放使用后可调过本步骤，首先点击左侧的 Model catalog，可以看到 Sora 2 模型的标签，点击 Check out model：

也可以在下方的模型列表找到想要的模型进行使用。

如果您没有使用 Sora 2 模型的权限，进入 Sora 2 模型介绍界面后将如下所示：

请点击 Request access 链接进行权限申请。

如您已经拥有 Sora 2 访问权限，可以点击 Use this model 进行模型部署：

部署过程非常简单，默认保持各类选项即可进行创建部署：

部署完成后，切换左侧菜单至 Models + endpoints，查看模型列表：

至此您就拥有了属于自己的 Sora 2 模型，可以开始使用！

通过 Azure AI Foundry Playground 使用 Sora 2

Azure AI Foundry 提供了强大的可视化界面，你可以无需写代码就生成视频。

1. 进入 Playground

打开 Azure AI Foundry 左侧菜单中的 Playgrounds，选择 Video playground：

进入 Playground 后选择 Sora 2 模型：

2. 填写提示词 Prompt

示例 Prompt：

A high-energy cyberpunk chase in the rain with neon reflections on wet streets. A futuristic motorcycle speeds through, dynamic motion blur capturing its sleek design and vibrant city lights.

3. 设置选项

可调节选项包括：

4. 生成视频

设置好后，点击 Generate 进行视频生成，视频生成成功后，你可以在 Generation history 中预览或下载视频：

通过 Python 调用 Sora 2

Azure 为 OpenAI 模型提供统一的接口，可以直接在你的后端调用。

1. 安装 SDK

pip install azure-ai-openai
pip install python-dotenv

2. 配置环境变量

创建 .env 文件：

AZURE_OPENAI_ENDPOINT=https://<your-resource-name>.openai.azure.com/
AZURE_OPENAI_KEY=<your-key>
AZURE_OPENAI_API_VERSION=2024-10-01-preview

3. Python 调用示例：文生视频

下面是最简可运行示例：

import os
from dotenv import load_dotenv
from azure.ai.openai import OpenAIClient
from azure.core.credentials import AzureKeyCredential

load_dotenv()

client = OpenAIClient(
    endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    credential=AzureKeyCredential(os.getenv("AZURE_OPENAI_KEY")),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION")
)

prompt = """
A cinematic shot of a spaceship flying through a nebula filled with colorful cosmic clouds.
"""

response = client.get_video(
    model="sora-2",
    prompt=prompt,
    duration=5,              # seconds
    resolution="1080p",
)

# 保存视频
video_bytes = response.video
with open("output.mp4", "wb") as f:
    f.write(video_bytes)

print("Video generated: output.mp4")

4. 使用结构化 payload

Sora 还支持更多控制，例如镜头、分镜头脚本、环境细节。

payload = {
    "prompt": "A cute corgi running on a beach during sunset.",
    "duration": 8,
    "resolution": "720p",
    "motion": "medium",
    "style": "realistic"
}

response = client.get_video(
    model="sora-2",
    **payload
)

with open("corgi_beach.mp4", "wb") as f:
    f.write(response.video)

生成最佳视频的技巧

1. 提示词结构推荐（General Prompt Template）

[主体对象] + [场景环境] + [动作] + [镜头效果] + [光影] + [风格]

示例：

A high-energy cyberpunk chase in the rain with neon reflections on wet streets. A futuristic motorcycle speeds through, dynamic motion blur capturing its sleek design and vibrant city lights.

2. 控制一致性

• 使用 seed 可重复生成风格一致的视频
• 合理设置 motion level 获得更自然的动作
• 提供清晰场景描述可减少模型误解

常见问题（FAQ）

1. 我试了但看不到 Sora 2？

目前需要访问权限。你需要：

• 联系 Azure 管理员
• 到模型页面确认已启用

2. 视频最大时长是多少？

具体限制依区域会有不同，通常为 ≤ 10 秒。

3. Python 生成的视频过小或无内容？

确保保存时使用 response.video 而不是错误字段。

总结

本文介绍了在 Azure AI Foundry 中使用 Sora 2 文生视频模型的两种方式：

• 使用可视化 Playground 快速体验
• 使用 Python SDK 在生产环境自动生成视频

Azure 的企业级安全合规能力让 Sora 2 成为企业落地视频生成的重要选择。

注意：本译文已获得的原文作者翻译授权，为避免广告嫌疑，本文中移除了特定产品和品牌的商业宣传内容，仅保留技术特性及企业级产品功能描述，相关内容请以原文为准。

随着各组织从大语言模型（LLM）的试验阶段迈向生产部署，选择哪种推理平台就成了一项关键的业务决策。这个选择不仅影响性能，也影响灵活性、成本优化，以及应对快速变化业务需求的能力。

对于技术人员和方案架构师在评估 LLM 推理平台时，应该重点考虑以下三大因素：

1. 架构灵活性：能否在不同硬件加速器和混合云环境间部署，而不会被某一家厂商锁定。
2. 运行可扩展性：支持从单 GPU 部署扩展到分布式多节点的高级部署模式。
3. 生态开放性：对最广泛的模型与内核支持，以及能与各种企业软件生态系统整合。

vLLM 在开源基础、先进内存管理能力，以及即将推出的分布式部署蓝图方面，独特地满足这些需求。与专有或硬件专用方案不同，这套组合提供了在成本、性能和运营需求上随时优化调整的自由。

本文将深入分析为何 vLLM 在其技术架构与能力上（尤其是其 KV-Cache 管理、并行策略，以及未来的 llm-d 分布式能力）提供了最可持续的生产级 LLM 部署路径。

开源优势

社区驱动的大规模创新

LLM 推理的发展，根本上受到开源创新的推动。过去一年半以来 vLLM V1: A Major Upgrade to vLLM’s Core Architecture | vLLM 博客（英文版），vLLM 在支持多样模型、功能和硬件后端方面取得显著成绩，从伯克利大学的研究项目成长为开源 AI 生态中的事实标准之一 vLLM 2024 Retrospective and 2025 Vision | vLLM 博客（英文版）。

vLLM 社区发展参考链接

vLLM 现在隶属于 PyTorch 基金会托管项目（GitHub — vllm-project/vllm: A high-throughput and memory-efficient inference and serving engine for LLMs），这保证了其长远的可持续性和治理机制。

企业支持与开源结合

许多企业及产品及解决方案对 vLLM 的态度类似于其对 Linux/OpenStack/Kubernetes 的策略：在社区驱动创新基础上，加入企业级支持、安全性和运维工具。这样模型即可部署在本地、公有云或混合云中，避免绑定。

这种方式带来的好处包括：

• 无厂商绑定：用户可自由选择部署环境
• 透明开发：安全漏洞与缺陷公开追踪与快速修复
• 社区贡献共享：一个组织开发的功能惠及整个生态
• 可定制性：源代码开放，可针对特定需求修改

此外，vLLM 在以下方面具备战略优势：

• 硬件无关性：不局限于 NVIDIA，支持 AMD、Intel、TPU 等多种平台（GitHub — vllm-project/vllm: A high-throughput and memory-efficient inference and serving engine for LLMs）
• 快速功能迭代：vLLM v1 对其核心模块（调度器、KV 缓存管理、worker、采样器、API 服务等）进行了全面重构（vLLM V1: A Major Upgrade to vLLM’s Core Architecture | vLLM 博客（英文版））
• 生态整合：原生兼容 Hugging Face、OpenAI API、Kubernetes 生态
• 成本优化：可以为不同工作负载选择最具性价比的硬件

架构灵活性与并行化策略

理解并行化（Understanding Parallelization）

大型语言模型带来了特殊的扩展挑战。例如：一个拥有 70B 参数 的模型，仅其权重（使用 FP16 精度）就需约 140GB 内存，这远远超过单一卡片的容量。基于 vLLM 及相关产品和解决方案通过四种互补的并行化策略来应对这些挑战，每一种策略都解决不同类型的扩展问题。

数据并行（Data Parallelism, DP）：跨请求扩展

数据并行是最简单的一种扩展模式：在多个服务器上运行完整模型的多个副本，每个副本处理不同的请求批次。在这种模式下：

• 维护完整模型：每个加速器／服务器保存整个模型的权重。
• 分配请求：请求由负载均衡器分发给不同的副本。
• 支持线性扩展：增加服务器数目可以线性提升吞吐量。
• 简化部署：部署相对简单，不需要对模型进行切分（sharding）。

          [负载均衡器]
               |
    ------------------------
    |          |           |
[Server1]  [Server2]  [Server3]
[Model A]  [Model A]  [Model A]
    |          |           |
[Batch 1]  [Batch 2]  [Batch 3]

关键：每台服务器都有完整的模型副本并行处理不同的请求

此模式与基于 KServe 的 Replica-Sets 用于模型副本服务很好的契合，能自动根据请求负载进行扩展，同时保有模型服务的简单性。

流水线并行（Pipeline Parallelism, PP）：按层分配

流水线并行将模型按照层（layers）分拆，不同的加速器处理不同的网络层：

• 顺序处理：请求在 GPU 间依次通过模型层进行处理。
• 内存均衡：内存需求在多个设备间较为均匀分布。
• 灵活部署：部署灵活，可以跨多个节点，不一定依赖特别高速的互联。
• 微批处理：通过微批处理（micro-batching）来保持 GPU 利用率。

Request → [GPU1:NN-Layers 1-8] → [GPU2:NN-Layers 9-16] → [GPU3:NN-Layers 17-24] → Response
             ↓                     ↓                      ↓
          [Memory]              [Memory]               [Memory]
          
时间线：请求按顺序流经 GPU

但流水线并行在现代 LLM 应用中也面临一些限制：

• “流水线气泡”（pipeline bubble）效率低下：某些 GPU 在等待上游阶段的数据时处于空闲状态。
• 通信开销高：阶段间数据传输成为瓶颈。
• 延迟敏感：每个阶段都会增加延迟，对“第一个 token 的时间”（time-to-first-token）有负面影响。
• 对 MoE（Mixture of Experts，混合专家模型）不友好：MoE 模型中只激活某些专家（非密集执行），这样无法很好地映射到按层划分的流水线结构中。

因为这些限制，很多生产环境更倾向于将张量并行（Tensor Parallelism）用于节点内部扩展，将数据并行（Data Parallelism）用于跨节点扩展。尽管如此，在内存受限或与其他并行策略组合使用的场景中，流水线并行仍然有价值。

张量并行（Tensor Parallelism, TP）：切分模型权重

当模型太大，单个加速器无法容纳其所有权重时，就使用张量并行来将模型权重拆分到多个 GPU 上：

• 水平层拆分：每次矩阵乘法操作被分配到多个 GPU，按部分计算。
• 同步计算：GPU 之间通过高速互联（如 NVLink、Infinity Fabric 等）进行同步和数据交换。
• 内存效率：可使得模型可服务的规模比单个 GPU 容量大出约 4～8 倍。
• 低延迟：如果硬件条件合适，通信开销低的话，张量并行还能保持较低的延迟。

Original Matrix Operation:
[Large Weight Matrix] × [Input] = [Output]

With Tensor Parallelism:
[Weight Part 1] → GPU1 ↘
[Weight Part 2] → GPU2 → [Combine] → [Output]
[Weight Part 3] → GPU3 ↗

关键：单矩阵运算跨 GPU 拆分，需要高速互连（NVLink）

vLLM 的张量并行实现是硬件无关的，支持多种互联技术和不同类型的加速器。

专家并行（Expert Parallelism, EP）：MoE 模型中的专家分布策略

对于混合专家模型（MoE），专家并行把不同的专家（experts）分配给多个 GPU 或多个节点，而不是让每个 GPU 都保存所有专家，由一个路由层（router layer）动态地将 token 分发给需要的专家：

• 分布式专家分片：专家（experts）被分片（shard）分布在不同的 GPU／节点，使拥有上百个专家的模型能扩展到远超过单设备的内存容量。
• 动态 token 路由：每个 token 只被发送到它应使用的一个或多个专家，以减少计算开销。
• 专家并行负载平衡（Expert Parallel Load Balancing, EPLB）：防止某些热门专家／专家组被频繁调用导致不均匀负载，通过动态复制或分布专家，以分散负载。
• 分层调度（Hierarchical Scheduling）：在多节点集群中，路由与复制先在节点间协调，再在节点内部的 GPU 间协调，确保整体利用率均衡且减少跨节点通信。
• 性能收益：对大型的 MoE 模型，这种专家并行在具有高速互联（NVLink、InfiniBand 等）的环境中可以实现接近线性扩展的吞吐效率。

               [Router Layer]
                      |
        ---------------------------------
        |          |          |         |
      GPU1        GPU2       GPU3      GPU4
    [Exp 1,2]   [Exp 3,4]  [Exp 5,6]  [Exp 7,8]
    
令牌流：路由器 → 选定专家 → 输出

vLLM 的统一策略

vLLM 的区别与优势在于它能够无缝结合这些并行策略，为分布式推理提供高度灵活性，使组织能够：

1. 混合使用策略：例如，在节点内部用张量并行，在节点间用流水线并行。
2. 根据硬件特性调整：基于可用的互联速度、GPU 内存、延迟敏感性等因素做最优规划。
3. 动态扩展：可以从单节点部署起步，随着需求增长扩展到多节点／多 GPU。
4. 保持 API 的一致性：无论使用哪种并行策略，道线路径、调用接口等对使用者尽量透明，不需要因为并行方式不同而改很多逻辑。

这种灵活性在混合云环境中尤其关键，因为不同环境（本地、云端、不同厂商硬件）之间的配置可能大不相同。

Hybrid TP+PP+EP+DP Deployment (MoE Model):

Pipeline Stage 1:               Pipeline Stage 2:              Pipeline Stage 3:
Node 1 (Attention Layers)       Node 2 (MoE FFN Layers)        Node 3 (Output Layers)
[Attn Part A] ←→ [Attn Part B]  [Router + Experts Subset]      [Out Part A] ←→ [Out Part B]
    GPU1           GPU2          GPU3: Experts 1-4                  GPU5            GPU6
         ↕ NVLink ↕              GPU4: Experts 5-8                       ↕ NVLink ↕
                                     ↕ NVLink ↕

Expert Distribution Detail (Node 2):
            [Router]
         GPU3  |  GPU4
        -------|-------
        Exp1   |  Exp5
        Exp2   |  Exp6  
        Exp3   |  Exp7
        Exp4   |  Exp8

Request Flow: → [Attention] → [MoE Layer/Router] → [Output] → Response
                              ↓
                    [Route to specific experts]

Parallelization Breakdown:
- Tensor Parallel (TP): Attention and Output layers split within nodes.
- Pipeline Parallel (PP): Different model stages across nodes .
- Expert Parallel (EP): MoE experts distributed across GPUs in Node 2.
- Data Parallel (DP): Entire pipeline can be replicated for more throughput.

更好的内存管理：KV-Cache（Key-Value 缓存）

在 LLM 推理中理解 KV-Cache

KV-Cache（键-值缓存）是 LLM 推理优化中最关键的特性之一。在注意力计算期间，模型必须访问先前 token 的表示 —— 随着序列长度增长，这个过程变得非常消耗内存。

高效的 KV-Cache 管理能决定同一硬件上能同时服务 10 个并发用户或 100 个并发用户，因为缓存复用将计算换成内存利用率。

(Q * K^T) * V computation process with caching

Step 1 (Prefill Phase)
                    Keys Transpose
                          ↓
    Queries              Keys              Values            Results
       |                  |                  |                  |
    [  Q  ]      ×     [  K  ]      →    [Scores]     ×    [  V  ]    →    [Output]
       |                  |                  |                  |
      64                 64                                    64              64
                          ↓                                     ↓
                    [Storing K]                           [Storing V]
                          ↓                                     ↓
                    ←── Cache memory (stores both K and V) ──→

Step N (Decode Phase)
                    Keys Transpose
                          ↓
    Query              Cached K            Cached V          Results
       |                  |                  |                  |
    [  q  ]      ×   [K₁...Kₙ]      →    [Scores]     ×   [V₁...Vₙ]   →    [output]
    (new)             (from cache)                         (from cache)       (new)
       |                  |                  |                  |
       1                 64                                    64               1
                          ↑                                     ↑
                    ←── Reading from cache (both K and V) ──→

Key Points:
- Prefill: Computes K and V for all input tokens, stores both in cache
- Decode: For each new token, reads ALL previous K and V values from cache
- Both K and V matrices must be cached (not just V)
- Cache size grows with sequence length

Prefill 阶段 vs Decode 阶段：两个截然不同的阶段

LLM 推理包含两个本质不同的阶段：

Prefill 阶段（Prompt 处理阶段）

• 并行处理所有输入 token。
• 计算密集型，GPU 利用率高。
• 为 prompt 中的所有 token 生成初始的 KV-Cache 条目。
• 延迟与 prompt 长度成正比。
• 大批量（larger batch sizes）带来好处。

Decode 阶段（Token 生成阶段）

• 一个 token 一个 token 顺序生成。
• 此阶段受限于内存带宽（memory-bandwidth bound）。
• 每新增一个 token，都要读取整个 KV-Cache 来自缓存的所有先前的 K 和 V。
• 延迟与输出 token 数量成正比。
• 依赖高效的缓存管理。

PagedAttention：vLLM 的内存革命

vLLM 引入 PagedAttention，这是一种在 KV-Cache 管理方面的突破性设计，它将 GPU 内存视为类似操作系统中的虚拟内存（virtual memory）来处理，其关键设计包括：

• 非连续存储（Non-contiguous Storage）：KV-Cache 块可以存储在 GPU 内存的任意地方，不必是连续的。
• 动态分配（Dynamic Allocation）：随着序列长度增长时才分配内存。
• 内存共享（Memory Sharing）：完全相同的 prompt 前缀（prompt prefixes）可以共享 KV-Cache 块。
• 几乎零浪费（Near-Zero Waste）：消除静态分配中常见的内部碎片问题。

这种设计让 vLLM 可以维持更大的批量大小、更高的并发性、以及比那些依赖静态、大型 KV-Cache 缓冲区的系统更好的 GPU 利用率。

连续批处理（Continuous Batching）：最大化 GPU 利用率

vLLM 的连续批处理机制带来了几个举措：

• 动态请求加入：新的请求可以在 decode 步骤之间加入正在运行的 batch。
• 提前完成处理：已经完成的序列立即释放资源。
• GPU 使用最优化：通过混合处理 prefill 与 decode 操作以保持高利用率。
• 支持抢占（Preemption）：可以暂停低优先级的请求以优先处理紧急请求。

在部署中的实际意义

这些内存管理上的创新在实际部署中带来了具体的效益：

1. 更高的并发性：在相同硬件上服务更多用户。
2. 更佳的成本效率：大幅减少基础设施需求。
3. 改善延迟：通过高效调度缩短 time-to-first-token。
4. 灵活性：可以处理变长的序列长度，而无需重新配置系统。

KV-Cache 优化在即将推出的 llm-d 分布式架构中变得尤为关键，因为高效的内存使用使得过去因内存约束而无法实现的新部署模式成为可能。

使用 llm-d 扩展：Kubernetes 原生的分布式推理

超越单服务器部署

虽然 vLLM 自身是高性能推理引擎，但在大规模生产环境中，还需要复杂的编排和智能请求调度。2025 年 5 月，红帽、Google Cloud、IBM 研究院、NVIDIA 和 CoreWeave 联手推出 llm-d，构建在 vLLM 之上的 Kubernetes 原生分布式推理栈。

llm-d 并不是 vLLM 的内置功能，而是一个补充的编排层。可以把它比作 Linux 与 Kubernetes 的关系：vLLM 负责推理引擎，llm-d 负责跨实例的调度与编排。它结合了三项开源技术：vLLM、Inference Gateway（AI 路由层）和 Kubernetes。

KServe 也在集成 llm-d，通过新的 LLMInference CRD，实现统一的服务接口，简化生成式 AI 的企业上手路径。

llm-d 将三大基础开源技术集成到一个统一的服务栈中：

• vLLM - 执行模型推理的高性能推理引擎。
• 推理网关（IGW） - 一个官方 Kubernetes 项目，通过 AI 感知路由扩展了 Gateway API。
• Kubernetes - 用于部署和扩展的行业标准编排平台。

通过整合这些技术，llm-d 使企业能够在混合云环境中大规模部署 LLM 推理，并实现最快的价值实现时间和极具竞争力的性价比。

三项关键创新

传统的负载均衡采用简单的轮询（round-robin）路由，对所有服务器一视同仁。llm-d 的 vLLM 感知调度程序能够做出智能决策，将请求路由到具有匹配缓存前缀的实例，根据实例是处理计算密集型预填充操作还是内存密集型解码操作来分配负载，并使用来自 vLLM 的实时可观测数据来避免实例过载，同时优先处理低延迟路径。这种智能路由可将基础设施成本降低 30% 到 50%，同时保持延迟 SLO。

解耦式服务（Disaggregated Serving）

llm-d 在生产规模上协调 vLLM 的本机分解服务（通过 KVConnector API），将预填充和解码分离到专门的工作节点中：

• 预填充工作节点：负责计算密集型的提示处理，使用高性能 GPU（如 H100、MI300X），并可根据需求独立扩展。

• 解码工作节点：专注于受内存带宽限制的 token 生成任务，使用具成本效益的 GPU（如 A100、L40S），并根据并发会话数进行弹性扩缩。

• KV 缓存传输：使用 NVIDIA NIXL 通过 UCX 提供高效的缓存移动，支持卸载到存储后端（未来交付）以及跨集群的全局缓存感知。

这允许适当规模的基础设施：昂贵的 GPU 仅用于预填充，成本优化的硬件可为数千个并发用户提供服务。

分布式前缀缓存（Distributed Prefix Caching）

llm-d 将 vLLM 的前缀缓存扩展到多个实例之间，通过两种方式实现：

• 本地缓存：在每个实例上将缓存卸载（offload）到内存或磁盘，几乎没有运维成本。

• 共享缓存（计划中）：通过实例之间的 KV 传输实现共享，并使用全局索引实现集群范围的缓存感知。

部署模式（Deployment Patterns）

llm-d 支持多种先进的企业部署模式：

• 异构硬件：根据工作负载混合 GPU 供应商和代数——用于预填充的高端 GPU、用于解码的成本优化 GPU 或用于低频请求的 CPU 集群。

• 动态扩缩：在高峰时段独立调整预填充容量，同时保持活动会话的稳定解码容量，并具有自动资源分配和故障转移功能。

• 地理分布（规划中）：在主数据中心部署集中式预填充工作者，并在用户附近部署边缘解码工作者，以实现低延迟响应。

多加速器与混合云支持

摆脱硬件锁定

AI 加速器快速演进，使市场变得多样化。专优化 NVIDIA 的方案如 TensorRT-LLM 虽然性能优秀，但容易导致锁定。vLLM 的硬件中立设计则允许用户自由选择最适合的加速器。

广泛硬件支持

vLLM 支持 NVIDIA GPU（针对 H100 进行一流的优化，支持 V100 及更新版本的所有 NVIDIA GPU）、AMD GPU（MI200、MI300 和 Radeon RX 7900 系列）、Google TPU（v4、v5p、v5e 和最新的 v6e）、AWS Inferentia 和 Trainium（trn1/inf2 实例）、Intel Gaudi（HPU）和 GPU（XPU）以及支持 x86、ARM 和 PowerPC vLLM 2024 Retrospective and 2025 Vision | vLLM 博客（英文版）。

这种广泛支持带来以下战略优势：

成本优化

• 选择 AMD MI300X，在特定工作负载下实现高性价比。
• 使用 AWS Inferentia，在 AWS 上进行经济高效的推理。
• 在低吞吐量用例中，可部署在现有 CPU 基础架构上。

供应链弹性

• 避免依赖单一 GPU 供应商的可用性。
• 通过多种选择协商更优惠的价格。
• 根据区域硬件可用性进行调整。

工作负载匹配

• NVIDIA H100 可实现最佳性能。
• AMD GPU 适用于开源部署。
• TPU 适用于 Google Cloud 部署。
• Intel Gaudi 适用于特定企业协议。

混合云部署模式

在企业级产品及解决方案中，vLLM 支持真正的混合云：

本地核心

• 在本地基础架构上处理敏感数据。
• 满足合规性要求的工作负载。
• 可预测的基线负载容量。

云爆发式扩展

• 利用云资源处理峰值负载。
• 试用新硬件（H100s、TPU v6e）。
• 无需基础设施投资即可实现地域扩展。

边缘推理

• 部署在适合边缘计算的硬件上。
• CPU 或更小的 GPU 推理。
• 与集中管理集成。

统一运维跨环境

借助企业级产品的相关功能，用户可从单一控制平面管理全部部署（公有云 + 私有云），主要从一下几个方面考虑。

• 单一控制平面：通过统一界面管理所有部署。
• 一致的 API：跨环境实现相同的应用程序集成。
• 统一监控：跨混合部署的聚合指标。
• 策略执行：一致的安全和合规策略。

模型生态与兼容性

支持广泛的开源模型体系

随着人工智能“淘金热”步伐的加快，vLLM 已发展到支持超过 100 种模型架构的高性能推理：涵盖几乎所有著名的开源大型语言模型（LLM）、多模态模型（图像、音频、视频）、编码器-解码器模型、推测解码模型、分类模型、嵌入模型和奖励模型。vLLM 2024 Retrospective and 2025 Vision | vLLM 博客（英文版）。与专注于有限模型系列的专业解决方案相比，这种全面的支持具有根本性的优势。

不只是传统 LLM

vLLM 的架构支持更多样的模型类型：

语言模型

• Llama 系列。
• Mistral 和 Mixtral 多模态模型。
• Google 的 Gemma 模型。
• IBM 的 Granite 系列。
• 阿里巴巴的 Qwen 模型。

多模态模型

• 视觉-语言模型（LLaVA, Qwen-VL）。
• 文档理解模型。
• 音频-语言模型。
• 视频理解能力。

专用架构

• 状态空间语言模型的生产支持，探索非 Transformer 语言模型的未来。vLLM 2024 Retrospective and 2025 Vision | vLLM 博客（英文版）。
• 混合专家（MoE）模型。
• 编码器-解码器架构。
• 嵌入和重排序模型。

模型集成简易流程

将新模型加入 vLLM 通常包括以下步骤：

1. 模型架构定义：使用熟悉的 PyTorch 模式实现。
2. Attention 后端集成：利用现有的优化内核。
3. Tokenizer 支持：兼容 Direct Hugging Face。
4. 配置映射：基于标准 YAML 的配置。

这样的标准化流程意味着组织能更快将新模型投入生产。例如，在 2025 年 8 月 GPT-OSS 发布后不久，vLLM 的 v0.11.0 版本就加入了对其生产部署的支持。

与 Hugging Face 生态整合

vLLM 与 Hugging Face 的原生兼容带来了便捷性：

直接模型加载

• 直接从 Hugging Face Hub 和/或兼容 S3 的对象存储后端（例如 MinIO）加载模型。
• 支持私有模型库。
• 自动权重转换处理。

分词器兼容性

• 使用现有的分词器实现。
• 支持自定义分词器。
• 快速分词器优化

配置保存

• 尊重特定于模型的配置。
• 支持自定义模型参数。
• 兼容经过微调的变体。

生产级模型管理

在一些企业级产品和方案中增加了模型生命周期的企业功能：

模型注册集成

• 已部署模型的版本控制。
• A/B 测试功能。
• 回滚机制。

模型监控

• 每个模型的性能跟踪。
• 使用情况分析和成本归因。
• 偏差检测功能。

面向未来的模型支持

模型创新速度极快，推理平台必须具备适应能力：

社区贡献

• 活跃的社区不断添加新模型。
• 供应商中立的开发流程。
• 快速集成突破性架构。

灵活的架构

• 模块化设计支持新的模型范式。
• 不受特定模型假设的约束。
• 为后转型架构做好准备。

企业验证

• 企业的测试和认证流程。
• 模型工件的安全扫描。
• 跨硬件性能验证。

这种全面的模型支持确保组织能够在新模型出现时立即采用它们，而无需进行平台迁移或架构更改，这是人工智能领域持续快速发展的一项关键能力。

使用企业级产品进行企业部署

从第一天起就是生产级

大多数企业级产品提供了一个灵活、可扩展的 MLOps 平台，提供构建、部署和管理 AI 应用的工具。它采用开源技术构建，为团队提供值得信赖且操作一致的功能，用于实验、模型服务和交付创新应用。了解更多关于企业级产品如何应对这一挑战的信息。

与 KServe 的整合：智能模型服务

在许多产品和方案中对 vLLM 与 KServe 的集成提供了企业级服务功能：

GenAI 功能

• 使用 vLLM 服务运行时进行多节点/多 GPU 推理。
• 通过 vLLM + LMCache 集成卸载键值缓存。
• 通过模型缓存高效重用模型。
• 集成 KEDA，允许基于外部指标自动扩缩。
• 通过与 Envoy AI Gateway 集成实现速率限制和请求路由。
• 通过 LLMInferenceService CRD 访问 llm-d 功能。

高级自动扩缩

• 基于请求的扩缩，实现资源利用率优化。
• 缩减​​至零功能，实现成本优化。
• 基于流量模式的预测性扩缩。
• 多指标扩缩（GPU 利用率、队列深度、延迟）。

流量管理

• 金丝雀部署，确保模型更新安全。
• 蓝绿部署，实现即时回滚。
• A/B 测试，用于模型比较。
• 影子流量，用于验证。

服务网格集成

• 使用 Istio 进行端到端加密。
• 高级路由和负载均衡。
• 熔断和重试逻辑。
• 用于调试的分布式跟踪。

自动化运维

• 健康检查和自动恢复。
• 资源优化建议。
• 自动化证书管理。
• 日志聚合和分析。

安全与合规

在企业部署中，必须重视安全：

访问控制

• RBAC 与企业身份提供商集成。
• 模型级访问权限。
• API 密钥管理。
• 所有操作的审计日志记录。

数据保护

• 静态和传输中加密。
• 私有端点选项。
• 网络策略实施。
• 合规性报告工具。

供应链安全

• 签名容器镜像。
• SBOM（软件物料清单）生成。
• 漏洞扫描。
• 基于策略的部署控制。

MLPerf 验证的性能

一些企业级解决方案和产品与众多知名服务器原始设备制造商（OEM）合作，使用搭载 NVIDIA GPU 和 vLLM 推理运行时的产品发布了令人印象深刻的 MLPerf 推理结果，在应对这一挑战方面取得了重大进展。加速生成式 AI 的采用，这些结果验证了：

• 规模化生产级性能。
• 高效的资源利用率。
• 负载下一致的延迟。
• 多实例协调能力。

集成可观测性

无需额外工具即可进行全面监控：

指标和仪表板

• 预建 Grafana 仪表板，用于 vLLM 指标。
• 预建 Grafana 仪表板，用于驱动路由决策的请求调度程序指标。
• 令牌生成率和延迟。
• GPU 利用率和内存使用率。
• 队列深度和拒绝率。

警报和响应

• SLA 违规自动警报。
• 与企业监控系统集成。
• Runbook 自动化功能。
• 容量规划洞察。

成本管理与优化（未来交付）

专为企业成本控制设计的功能：

• 计费/显示：按团队或项目跟踪使用情况。
• 资源配额：防止成本失控。
• 竞价型实例支持：降低批量工作负载的成本。
• 空闲检测：自动缩减未使用的资源。

这个企业级平台将 vLLM 从高性能推理引擎转变为完整的生产解决方案，可用于关键任务部署。

特性对比：vLLM vs TGI vs TensorRT-LLM

✓ = 全面支持，◐ = 部分/有限支持，✗ = 不支持

企业级产品与开源 vLLM 的主要区别

• 硬件灵活性：最广泛的加速器支持，包括 AMD、Intel、Google TPU 和 CPU。
• 模型生态系统：支持超过 100 种模型架构，而其他替代方案仅有 25-40 种。
• 分布式架构：即将推出的 llm-d 支持分解式预填充/解码和系统级 kv-cache 路由，以实现分布式最优扩展。
• 企业集成：企业级产品集成 KServe 自动扩展。
• 内存效率：先进的 PagedAttention 和 KV-Cache 管理。
• 开放开发：PyTorch 基金会项目，社区创新迅速。

如何作出正确选择

文中给出一个简单的决策框架：对每个判断点打 “Yes”：

• 0–2 个 “Yes”：可考虑专用方案（若其满足你的特定需求）
• 3–5 个 “Yes”：vLLM 在你的场景中将提供显著优势
• 6+ 个 “Yes”：基于 vLLM 的企业级产品是战略性选择

每个决策点都涉及基本的架构约束：

• 灵活性要求决定您是否需要与硬件无关的解决方案。
• 运营复杂性评估简化的运营是否值得采用开源技术。
• 模型与创新评估快速发展是否需要一个适应性强的平台。
• 长期可持续性考虑总体拥有成本和战略风险。

战略推荐

如果你对多个维度都倾向 “Yes”，那 vLLM + 企业级产品将提供：

• 最大的灵活性：可在任何受支持的硬件上部署。
• 优秀的运维体验：企业级平台，复杂性极低。
• 面向未来的能力：支支持新兴模型和架构。
• 成本优化：为每种工作负载选择最佳硬件。
• 风险控制：开源基础，提供企业级支持。

这些因素的融合使得 vLLM 成为构建可持续人工智能基础设施的组织的战略选择。

采纳步骤建议

立即阶段

• 在开发环境部署 vLLM + 企业级产品
• 用自己的模型和工作负载进行测试
• 验证硬件灵活性与性能

短期阶段

• 实施 KServe 的自动扩缩能力
• 建立监控与可观察性体系
• 培训团队操作流程

中期阶段

• 设计生产部署架构
• 若需要，实施混合云模式
• 为 llm-d 分布式架构做准备

长期阶段

• 优化成本（选硬件、资源调度）
• 引入更高级部署模式
• 将自己的改进贡献给社区

总结

选择 LLM 推理平台代表着一项战略承诺，它将影响您组织未来几年的人工智能能力。

我们的分析表明，企业级产品上的 vLLM 独特地满足了企业 LLM 部署的三个关键要求：

1. 灵活性：可在任意硬件与混合云环境部署
2. 可扩展性：先进内存管理与 llm-d 架构使资源利用效率提升 10–100 倍
3. 可持续性：开源基础 + 企业支持，避免陷入锁定

虽然 TensorRT-LLM 提供了 NVIDIA 专属优化，TGI 也提供了 Hugging Face 集成，但“只有 vLLM 能够提供快速发展的 AI 领域所需的架构灵活性”。 凭借对 100 多种模型架构的支持、与硬件无关的设计以及 PyTorch 和 Linux 基金会的支持，->“搭载 vLLM 的企业级产品为长期成功奠定了最坚实的基础”。

• 模型参数（Parameters, P）动辄上百 GB，需要长期驻留显存。
• 输入/输出数据（Data, D）则随请求动态变化，但往往和参数耦合在同一设备上，导致显存占用不均衡，扩展性受限。

为了解决这一问题，可以借助 vLLM 框架实现参数 / 数据（P/D）分离，提升推理系统的灵活性和吞吐。

大模型推理的资源瓶颈

以一个 70B 规模的 Transformer 模型为例：

• 参数权重（FP16 存储）约需 140GB 显存；
• 每次请求输入的序列数据、KV Cache 会消耗额外显存，并随 batch size 增长而急剧膨胀。

如果不加区分地将 P 与 D 放在同一块 GPU：

1. 参数长期驻留，挤压了用于动态数据的显存；
2. 多实例并发时，数据显存不足，限制了吞吐。

因此，在分布式推理系统中，业界逐渐采用 参数与数据分离（P/D Separation） 的架构思路。

vLLM 简介

vLLM 是一个高性能的大模型推理引擎，核心优势包括：

• PagedAttention：高效管理 KV Cache，支持大批量并发；
• 高吞吐率：相较于 Hugging Face Transformers 推理，吞吐提升数倍；
• 灵活的分布式支持：可结合 DeepSpeed、Megatron 等方案，支持参数/数据分布式存储与调度。

vLLM 的模块化架构，使其天然适合实现 P/D 分离。

P/D 分离的实现思路

在 vLLM 中，推理流程大致分为两个部分：

1. 参数侧（P）

   • 模型权重加载与存放；
   • 可通过 ZeRO-3 / Tensor Parallel 等策略将参数分布在多 GPU 节点上；
   • 参数在整个推理生命周期中保持常驻，不随请求波动。

2. 数据侧（D）

   • 动态输入序列、KV Cache、采样状态等；
   • 可使用 PagedAttention 管理显存分页；
   • 支持把部分 KV Cache 放到 CPU/Host 内存，再动态迁移到 GPU。

核心机制

其核心机制是显存资源隔离：

• 权重（P） 固定驻留在专门的 GPU（参数节点）；
• 数据（D） 可以按需分配到其他 GPU（数据节点），甚至利用 CPU 内存 / NVMe。

这样：

• 参数显存不与动态数据抢占空间；
• 数据可以根据请求动态扩展，提升并发能力。

在 vLLM 中的实现路径

实现 P/D 分离的常见方法：

1. 参数分片（Parameter Sharding）

   • 借助 vLLM 对 Megatron-LM / DeepSpeed 的支持，将模型参数按张量维度切分到多 GPU；
   • 仅在推理计算时聚合，不需要在每个设备上完整存放参数。

2. KV Cache 分离（Data Sharding）

   • 通过 vLLM 的 PagedAttention，可以把 KV Cache 存在独立的 GPU 或 Host 内存；
   • 在推理过程中按需调页，类似操作系统的虚拟内存机制。

3. Pipeline 并行化

   • 将模型计算划分为不同阶段，前几层专门占用参数节点，后几层在数据节点完成；
   • 在流水线中，数据逐层传递，而参数保持分片驻留。

基于 vLLM 的 P/D 分离实战

下面给出两部分内容：

• 配置示例：如何在多 GPU 环境下指定参数和数据分布；
• 代码示例：如何加载模型并运行推理，展示参数常驻、数据动态分配。

配置示例

假设我们有 4 张 GPU：

• GPU 0,1：专门存放模型参数（P）；
• GPU 2,3：主要承载 KV Cache 等动态数据（D）。

我们可以在启动 vLLM 时设置：

CUDA_VISIBLE_DEVICES=0,1,2,3 \
python -m vllm.entrypoints.api_server \
    --model /path/to/llama-2-70b \
    --tensor-parallel-size 2 \
    --gpu-memory-utilization 0.85 \
    --enable-chunked-prefill \
    --enforce-eager \
    --kv-cache-dtype fp16 \
    --max-num-batched-tokens 4096

这里的关键点：

• --tensor-parallel-size 2：只在 GPU 0,1 上做参数分片存放；
• --gpu-memory-utilization：控制参数占用的比例，留出余量给数据；
• --kv-cache-dtype fp16：降低 KV Cache 精度，减少数据显存占用；
• vLLM 内部的 PagedAttention 会自动把 KV Cache 分配到 GPU 2,3，如果溢出则回退到 CPU 内存。

代码示例

下面是一个 Python 调用示例：

from vllm import LLM, SamplingParams

# -------- 参数（P）分离 --------
# tensor_parallel_size=2 表示参数分布在前两张 GPU（0,1）
llm = LLM(
    model="/path/to/llama-2-70b",
    tensor_parallel_size=2,
    gpu_memory_utilization=0.85,
    enforce_eager=True,       # 避免显存碎片
    enable_chunked_prefill=True,
    kv_cache_dtype="fp16"     # 数据（D）使用更轻量的缓存精度
)

# -------- 数据（D）分离 --------
# PagedAttention 会自动管理 KV Cache 的存放位置（GPU2, 3, 甚至 CPU 内存）
sampling_params = SamplingParams(
    temperature=0.8,
    top_p=0.95,
    max_tokens=256
)

prompt = "解释一下通过 vLLM 实现 P/D 分离的好处。"

# 运行推理
outputs = llm.generate([prompt], sampling_params)

print("模型输出：")
for output in outputs:
    print(output.outputs[0].text)

验证方式

运行时可以用 nvidia-smi 观察：

• GPU 0,1 显存几乎恒定，主要承载参数；
• GPU 2,3 的显存随请求数量/序列长度波动，主要承载 KV Cache；
• 如果输入过大，KV Cache 会溢出到 CPU 内存，但仍可继续推理。

实际效果与收益

通过 P/D 分离，可以得到以下好处：

• 提升 GPU 利用率：参数和数据分工明确，避免显存冲突；
• 支持更大 batch size：数据显存可扩展，吞吐率提升显著；
• 降低成本：参数可驻留在高端 GPU，而数据可放到中低端 GPU 或 CPU 内存，形成分层存储；
• 灵活性：适配多种硬件资源组合（A100 + H100, GPU + CPU, GPU + NVMe）。

在实践中，结合 vLLM 的 PagedAttention，P/D 分离的效果尤为明显，可让大模型推理在同样硬件下实现 数倍并发提升。

总结

vLLM 框架凭借其高效的 KV Cache 管理和分布式能力，为 大模型推理的 P/D 分离 提供了坚实基础。 通过将 参数（P） 和 数据（D） 解耦，可以更好地利用硬件资源，提升推理性能与扩展性。

未来，随着 混合精度存储、分层缓存（GPU+CPU+NVMe） 的发展，P/D 分离架构将逐渐成为大模型推理的主流范式。

VibeVoice 是 Microsoft Research 发布的一套面向长篇、多说话人、对话式语音合成的研究框架，目标场景例如整集播客、有声剧或访谈：能在单次生成中维持说话人一致性并处理自然的换手（turn-taking）。模型家族包含多个规模（例如 1.5B、7B 等），并在 Hugging Face 上以 microsoft/VibeVoice-1.5B 形式开放（模型卡、模型文件、model card 中有安装/使用与责任使用说明）。

它解决了传统 TTS（Text-To-Speech）系统的一些痛点，比如：

• 难以维持长时间对话的语音一致性（speaker consistency）；
• 多说话人的切换自然性（turn-taking）差；
• 效率低 — 长文本 + 多说话人时，资源消耗大。

核心创新与架构

VibeVoice 有几个比较新的或者关键的技术设计：

架构图如下：

优点和局限

优点

1. 长篇幅对话能力 — 能生成近 90 分钟的连续对话，并维持说话人一致性。
2. 多说话人支持 — 最多支持 4 个不同说话人的切换，且对话流程自然。
3. 压缩效率高 — 用 7.5 Hz 帧率的 speech tokenizer，音频被高度压缩但仍保证质量。
4. 语义 + 声学分离 — 语义 tokenizer（semantic）负责内容，声学 tokenizer（acoustic）负责声音细节，两者协同。

局限

1. 语言支持有限 — 目前主要是英语与中文，跨语言能力还在研究中。
2. 背景音乐 / 音效不支持 — 当前专注纯语音合成，没有加入背景音或重叠说话人（speaker overlap）。
3. 仓库暂时关闭 — 官方声明因 “部分用途超出初衷 / 不符合责任使用” 的情况，仓库暂时被 disable。意味着可能无法立即拿到源码或全部功能。
4. 硬件要求 / 资源消耗 — 虽然压缩效率高，但生成长篇语音 + 多说话人 + 高保真度仍需要较好的 GPU 资源。
5. 潜在滥用风险 — 用来做语音克隆、假扮、deepfake 等可能的恶意用途。官方在文档中也提到要谨慎。

快速上手

下面给出具体实现步骤及上手流程。注意：由于官方仓库目前不包含完整脚本，实际推理通常依赖社区实现或 Hugging Face Spaces / Colab 示例。所列步骤已参考 Hugging Face 模型页与社区示例仓库。

先决条件

• Python 3.8+；建议在隔离虚拟环境（venv / conda）中操作。

• GPU：带 CUDA 的 NVIDIA GPU（具体 VRAM 与性能见第 5 节）。若使用 Apple Silicon / macOS，可参见社区讨论与专门脚本。

• 安装工具（示例）：

  • pip install huggingface_hub transformers accelerate torch soundfile torchaudio numpy einops
  • 本地需要 ffmpeg（用于音频切分/拼接与格式转换）。

  具体版本请按 PyTorch 官网或社区脚本说明选择（不同 CUDA 版本的 wheel 不同）。参考社区仓库的 requirements 列表以确保兼容。

下载模型权重

from huggingface_hub import snapshot_download
model_dir = snapshot_download("microsoft/VibeVoice-1.5B")
print("模型已下载到", model_dir)

注意：snapshot_download 会把 HF 模型文件和模型卡同步拉取到本地；若模型文件较大，请确保磁盘与网络条件。

使用社区推理脚本

很多社区仓库或 Hugging Face Spaces 提供了 demo/inference_from_file.py 之类的脚本。示例命令：

# 在 Colab / 本地环境中操作
git clone https://huggingface.co/technicalheist/vibevoice-1.5b
cd vibevoice-1.5b
# 安装 Python 依赖（按模型页 “Requirements” 部分）
pip install torch transformers soundfile ffmpeg-python  # plus 其他必要包

# 创建一个 transcript 文件，比如 transcript.txt
echo "Speaker 1: Hello, how are you doing?
Speaker 2: I'm good, thanks. What about you?" > transcript.txt

# 用 demo 脚本生成语音
python demo/inference_from_file.py \
  --model_path /path/to/technicalheist/vibevoice-1.5b \
  --txt_path transcript.txt \
  --speaker_names "Alice,Bob"

社区实现（例如 technicalheist/vibevoice-1.5b、shijincai/VibeVoice 等）提供了可运行的示例与依赖说明；使用前请仔细阅读其 README 并依据其中的依赖和指引来配置环境。示例脚本名与参数在不同实现中可能不同，请以具体仓库中的文档为准。

简单示例

Speaker 1: Hello, welcome to our podcast.
Speaker 2: Thanks — happy to be here. Let's talk about VibeVoice.
Speaker 1: Sure, start with the key idea...

将上面保存为 transcript.txt 并传入 --txt_path 即可（脚本会解析说话人标记并输出对应音轨）。社区脚本通常会把每个说话人的音色/说话风格作为参数或示例内置。

结论

微软的 VibeVoice 是当前 TTS / 语音合成领域一个非常令人兴奋的进展。它在长篇幅语音 + 多说话人上取得了突破，尤其是在对话流畅性和说话人一致性方面，技术设计（如低帧率的双 tokenizers + next-token diffusion + LLM 架构）也很前沿。

如果你正在做播客、有声书或者对话剧本的语音合成，这可能是一个非常有用的工具／研究基础。不过在商业部署或者包含敏感语音身份／法律边界用途时，需要格外注意责任使用，以及是否有完整的许可与风险评估。

SGLang 简介

SGLang 是一款面向大语言模型（LLM）和视觉语言模型（VLM）的高性能推理框架，通过精心设计的后端运行时与前端语言协同工作，使模型交互更加高效且可控。其核心优势包括：

• 高效后端运行时：采用创新的 RadixAttention 技术实现前缀缓存，支持跳跃式受限解码、零开销 CPU 调度、连续批处理、令牌注意力（分页注意力）、张量并行、FlashInfer 内核、分块预填充以及多种量化技术（FP8/INT4/AWQ/GPTQ），显著提升推理效率。
• 灵活前端语言：提供直观且强大的 LLM 编程接口，支持链式生成调用、高级提示工程、复杂控制流、多模态输入、并行处理及外部系统交互。
• 广泛模型兼容性：支持多种主流生成式模型（Llama、Gemma、Mistral、QWen、DeepSeek、LLaVA 等）、嵌入模型（e5-mistral、gte）及奖励模型（Skywork），并提供简便的新模型扩展机制。
• 活跃开源生态：拥有蓬勃发展的社区支持，已获得广泛业界认可（截至 2025 年 3 月 17 日，GitHub 累计星标超过 12,000）。

其技术架构如下：

除此之外，对于初学者，需要了解其以下特性：

• OpenAI 兼容 API：直接用 openai Python SDK 或 cURL 调用，不用改你的上层业务代码。
• 高吞吐与低延迟：结合连续批处理与前缀缓存等技巧，让相同前缀的请求复用计算。
• 生产友好：支持多并发、流式输出、可与 Hugging Face 模型库直接对接。

环境准备

工欲善其事必先利其器，要完成本文的新手实验，需准备如下环境：

• 操作系统：建议 Linux（常用为 Ubuntu 20.04+）。WSL2 也可尝试。
• Python：建议 3.10 或 3.11。
• GPU：建议 NVIDIA 显卡，24GB 显存可跑 7B/8B 级（如 Llama 3.1 8B）。没有 GPU 也能跑小模型或量化模型，但性能有限。
• 模型来源：Hugging Face（如 meta-llama/Llama-3.1-8B-Instruct）或本地路径。

安装 SGLang

环境就绪后，使用 pip 安装 SGLang（确保已安装 pip、可选创建虚拟环境）。

pip install sglang openai huggingface-hub

如果你需要从 Hugging Face 自动下载私有或受限模型，请先登录或设置 Token：

huggingface-cli login
# 或
export HF_TOKEN=您的Token

启动 SGLang 服务

可以通过以下两种启动方式进行 SGLang 服务的启动。不同版本的 SGLang 命令行参数可能略有差异，如果出现参数名称不匹配，先执行 –help 查看本机版本支持的参数。

通过 launcher 启动

python -m sglang.launcher \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 30000 \
  --tp 1 \
  --max-model-len 8192

其中常用参数说明如下：

• –model：Hugging Face 模型名称或本地模型权重路径
• –host/–port：服务监听地址与端口
• –tp：Tensor Parallel 并行度（单卡设为 1；多卡可根据需要设为 2、4 等）
• –max-model-len：上下文最大长度

另外需要注意以下两点：

• 如果使用的是 Hugging Face 模型，首次运行会下载模型权重，请确保网络通畅。
• 如果显存吃紧，可优先尝试更小模型，或减少 –max-model-len。

通过 sglang 命令启动

如果您使用的版本提供 sglang serve 命令，也可使用如下命令进行启动：

sglang serve -m meta-llama/Llama-3.1-8B-Instruct --host 0.0.0.0 --port 30000

快速验证

服务启动后，OpenAI 兼容接口即可使用：

curl http://127.0.0.1:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer EMPTY" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "用两句话介绍一下你自己。"}
    ],
    "max_tokens": 128,
    "temperature": 0.2
  }'

如果运行正常，将返回标准的 ChatCompletion JSON 响应。

使用 Python OpenAI SDK 进行调用

非流式调用（最简单的问答）：

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:30000/v1",
    api_key="EMPTY"  # 本地服务通常不校验
)

messages = [
    {"role": "system", "content": "You are a helpful assistant who answers in Chinese."},
    {"role": "user", "content": "请用三句话介绍帕累托最优。"}
]

resp = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=messages,
    temperature=0.2,
    max_tokens=256
)

print(resp.choices[0].message.content)

流式输出（边生成边打印）：

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:30000/v1", api_key="EMPTY")

messages = [
    {"role": "system", "content": "You are a helpful assistant that speaks Chinese."},
    {"role": "user", "content": "简述 Transformer 的核心思想，并给出一个现实类比。"}
]

stream = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=messages,
    temperature=0.2,
    max_tokens=300,
    stream=True
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta:
        delta = chunk.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)

print("\n[Done]")

通过以上两种方式，我们可以构建自己的推理服务应用，也可以通过市面上开源的软件来接入您部署的推理服务，如 Open-WebUI 等。

常见问题与排错

• 启动时报显存不足（CUDA OOM）
  • 尝试更小的模型（如 7B/8B）、减小 --max-model-len、或降低并发。
  • 如果有多卡，增加 –tp 并用多卡分摊显存。
• 拉取模型失败或速度慢
  • 先执行 huggingface-cli login；或提前手动把模型权重下载到本地路径，并在 --model 里填本地路径。
• API 报 Unknown argument
  • 不同版本的命令行参数可能有差异。请运行：python -m sglang.launcher --help
  • 根据你安装的版本调整参数名，如 --model / --model-path、--tp / --tensor-parallel-size 等。
• Python 客户端 401/Key 错误
  • 本地服务通常不校验 Key，只要带上一个占位即可（如 EMPTY）。
• 流式输出不打印
  • 确认传了 stream=True；迭代 chunk 时取 choices[0].delta.content。
• 并发性能不达预期
  • 尝试用 Async 客户端并发请求；避免在单线程里串行等待。
  • 检查 GPU 利用率；确认没有 CPU/GPU 数据传输瓶颈。

总结

至此，你已经完成了：

• 安装与启动 SGLang 服务
• 用 OpenAI 兼容接口进行非流式与流式推理

祝你上手顺利，玩得开心！如果遇到命令行参数或 API 的小差异，参考本地版本的 –help 与官方文档进行快速适配即可。