TabbyAPI：基于 ExLlamaV3 的开源 OpenAI 兼容量化模型推理服务｜部署与使用全指南

项目仓库： https://github.com/theroyallab/tabbyAPI

开源协议：AGPL v3 · 交付形态：FastAPI Python 应用 + Docker 镜像（CUDA 12.8 / CUDA 13 / ROCm）· 主要语言：Python · 部署方式：Docker 一键启动或源码运行 · 默认端口：5000 · 官方 API 文档：theroyallab.github.io/tabbyAPI

仓库迁移说明：项目清单中记录的 theroyall/tabbyAPI 已不存在，当前官方仓库为 theroyallab/tabbyAPI；官方 README 明确声明该仓库是 TabbyAPI 信息的唯一官方来源，其他站点、下载或服务均与项目无关，应视为不可信。

1 项目简介

TabbyAPI 是 theroyallab 团队用 FastAPI 编写的 LLM 推理服务器，底层使用 ExLlamaV3 作为推理后端，同时也是 ExLlamaV3 的官方 API 后端。它对外提供与 OpenAI 兼容的 /v1/chat/completions、/v1/completions 等接口，可以直接被 SillyTavern、LibreChat、Open WebUI 等前端以 OpenAI Client 方式接入。

官方定位声明（务必先读）：README 明确标注 TabbyAPI 是 rolling release，可能存在 bug 与变更；它是一个面向少量用户的 hobby 项目，不 meant to run on production servers，生产级工作负载请选择其他方案。本文按官方 README 与 Wiki 口径整理，用于个人本地与内网开发场景。

1.1 核心信息一览

1.2 适用场景

• 本地或内网部署量化模型（EXL3 / GPTQ / FP16 / BF16），希望用 OpenAI 兼容接口被各种前端接入。
• 在 NVIDIA Ampere 及以上 GPU 上利用 paged attention 做连续批处理，提升并发吞吐。
• 需要动态加载 / 卸载模型、通过 API 下载 Hugging Face 模型、挂 LoRA、用 draft model 做推测解码。
• 想接入 AI Horde、用 JSON Schema / Regex / EBNF 约束输出格式，或在代理层覆盖客户端采样参数。

1.3 能力边界（官方口径）

• 官方 README 明确：项目为 rolling release，可能有 bug 与变更，必要时需要重装依赖。
• 官方明确：hobby 项目，不面向生产服务器；生产负载请选其他方案。
• 模型类型官方支持 Exl3（高度推荐）与 FP16/BF16；paged attention 并行批处理要求 NVIDIA Ampere GPU 及以上。
• 除本仓库外的站点、下载、服务均非官方，应视为不可信。
• AGPL v3 协议要求二次开发与网络服务对外提供时开源衍生代码。

2 功能特性

2.1 OpenAI 兼容接口

• 提供 /v1/chat/completions、/v1/completions 等 OpenAI 风格端点，可直接替换 base_url 接入。
• 支持 OAI 风格的 tool / function calling。
• 聊天模板使用符合 HuggingFace 规范的灵活 Jinja2 模板引擎。

2.2 推理后端与性能

• 基于 ExLlamaV3 后端，使用异步 asyncio 并发推理。
• 连续批处理引擎使用 paged attention（NVIDIA Ampere 及以上）。
• 支持通过 draft model 做推测解码（speculative decoding）。
• ExLlamaV3 使用 POSIX 共享内存做 tensor parallelism 与 CPU MoE offload，因此容器需要 --shm-size 大于默认 64 MiB。

2.3 模型与运行时能力

• 运行时加载 / 卸载模型。
• 通过 API 从 Hugging Face 下载模型。
• 支持 embedding 模型（latest-extras 镜像 tag，或源码构建时 --build-arg EXTRAS=1）。
• 支持 LoRA 适配器。
• 内置代理层，可覆盖客户端请求参数与采样器。

2.4 输出约束与生态

• 支持 JSON Schema、Regex、EBNF 约束生成。
• 支持 AI Horde。
• 与 SillyTavern、LibreChat、Text Generation WebUI 等前端原生兼容。

3 官方界面预览

TabbyAPI 是纯 API 服务，官方提供的"界面"是 theroyallab.github.io/tabbyAPI 上的 OpenAPI 交互式文档；该页面明确说明"not meant to send requests"，仅用于查看接口。本文不另行配图，避免使用第三方截图。

4 官方跳转链接汇总

• 仓库地址：https://github.com/theroyallab/tabbyAPI
• API 文档（OpenAPI）：https://theroyallab.github.io/tabbyAPI
• Wiki（入门指南）：https://github.com/theroyallab/tabbyAPI/wiki/01.-Getting-Started
• Docker 详细说明：docs/01.-Getting-Started.md#docker
• ExLlamaV3 后端：https://github.com/turboderp-org/exllamav3
• ExLlamaV2 后端：https://github.com/turboderp-org/exllamav2
• 视频指南：https://www.youtube.com/watch?v=03jYz0ijbUU
• Discord 社区：https://discord.gg/sYQxnuD7Fj

5 前置要求与服务器配置

5.1 软件前提

• 操作系统：Linux（Docker 部署最常见）；Windows / macOS 通过 Docker Desktop 亦可。
• Docker 与 NVIDIA Container Toolkit。
• NVIDIA 驱动需兼容 CUDA 12.8（latest 与 latest-extras tag）或 CUDA 13（cu13 tag）；AMD 用户使用 latest-rocm 镜像（Radeon RX 7900 系列），其他 AMD GPU 需从 docker/Dockerfile.rocm 自建。

5.2 硬件建议

• NVIDIA Ampere（A100 / RTX 30 系列）及以上才能使用 paged attention 连续批处理。
• 量化模型显存需求按模型大小与位宽估算；ExLlamaV3 支持 CPU MoE offload，但仍建议预留足够内存。
• 容器必须 --shm-size=8g（或更大），因为 ExLlamaV3 用 POSIX 共享内存做 tensor parallelism 与 CPU MoE offload，Docker 默认 64 MiB 不够。

5.3 端口与目录

6 方式一：Docker 一键部署（推荐）

6.1 拉取并启动官方镜像

docker pull ghcr.io/theroyallab/tabbyapi:latest

docker run --gpus all --shm-size=8g --name tabbyapi \
  -p 5000:5000 \
  -v /path/to/models:/app/models \
  ghcr.io/theroyallab/tabbyapi:latest

把 /path/to/models 替换为包含本地模型目录的宿主机路径。启动后 API 暴露在 http://localhost:5000。

6.2 可用镜像 tag

6.3 验证

curl http://localhost:5000/v1/models \
  -H "Content-Type: application/json"

把任意 OpenAI 兼容客户端的 base_url 指向 http://localhost:5000/v1，api_key 任意（按配置）。

6.4 Compose / 自定义配置 / 本地构建

Docker Compose、自定义配置挂载、本地构建镜像的细节见官方 Docker 说明；从源码构建并包含 embeddings 栈时传 `--build-arg EXTRAS=1`。

远程访问注意事项：默认绑定本机，生产暴露前请加反向代理与鉴权；官方明确项目不面向生产服务器，公网部署请自行评估风险。

7 方式二：源码 / 本地运行

7.1 克隆仓库

git clone https://github.com/theroyallab/tabbyAPI.git
cd tabbyAPI

7.2 安装依赖

Python 版本范围：3.10–3.14（README 徽章）。建议使用虚拟环境：

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

详细安装、配置、模型目录组织请参考官方 Wiki Getting Started。

7.3 启动

python main.py

启动后监听 http://localhost:5000。

8 配置项说明

TabbyAPI 的配置文件（config.yaml / model_config.yaml）字段较多，完整字段以官方 Wiki 与 docs/01.-Getting-Started.md 为准。常见入口：

具体字段名与默认值以官方 Wiki 与示例配置为准，本文不臆造环境变量。

9 常用运维命令

# 查看运行中的容器
docker ps | grep tabbyapi

# 查看日志
docker logs -f tabbyapi

# 停止
docker stop tabbyapi

# 启动
docker start tabbyapi

# 更新镜像
docker pull ghcr.io/theroyallab/tabbyapi:latest
docker rm -f tabbyapi
# 然后按 6.1 重新 docker run

# 进入容器排查
docker exec -it tabbyapi bash

# 查看 GPU 占用
nvidia-smi

# 列出已加载模型
curl http://localhost:5000/v1/models

备份：模型目录通过 -v 挂载在宿主机，直接备份该目录即可；容器本身不存状态。

10 常见故障排查

• 启动报共享内存不足 / tensor parallelism 失败：忘记加 --shm-size=8g；Docker 默认 64 MiB，ExLlamaV3 用 POSIX 共享内存做 tensor parallelism 与 CPU MoE offload。
• 看不到 GPU / could not select device driver：未安装 NVIDIA Container Toolkit，或宿主机驱动版本与镜像 CUDA 版本不匹配；latest 镜像要求 CUDA 12.8，cu13 要求 CUDA 13。
• paged attention 不可用：官方仅支持 NVIDIA Ampere GPU 及以上；Turing / Volta 及以下只能走普通路径。
• 模型加载失败：检查 /path/to/models 是否正确挂载到 /app/models；模型格式需为 Exl3（推荐）或 FP16/BF16。
• 想启用 embedding 模型：使用 latest-extras tag，或源码构建时 --build-arg EXTRAS=1；普通 latest 镜像不含 embedding 栈。
• 遇到 bug / 需要重装依赖：官方自述 rolling release，遇到依赖问题可重装镜像或重建 venv；反馈前先查 Wiki 与 Issues。
• 从第三方站点下载 TabbyAPI：官方 README 明确声明本仓库是唯一官方来源，其他站点应视为恶意；只从 ghcr.io/theroyallab/tabbyapi 与 github.com/theroyallab/tabbyAPI 获取。
• AGPL v3 合规：对外提供网络服务时需按 AGPL v3 开源衍生代码，商用前请阅读 LICENSE。

11 风险与合规说明

• TabbyAPI 采用 AGPL v3 协议，强 copyleft；二次开发与网络服务对外提供时需开源衍生代码，商用前请咨询法务。
• 官方明确项目为 rolling release 的 hobby 项目，不面向生产服务器；本文不鼓励在公网生产环境直接暴露。
• 模型权重版权归各模型作者所有，使用 EXL3 / GPTQ 等量化格式时需确认原模型许可允许量化与分发。
• 本文所有命令、端口、镜像 tag、版本要求均来自官方 README 与 Wiki；后续版本演进以官方仓库最新说明为准。