# ogguf

**Repository Path**: lowkey110/ogguf

## Basic Information

- **Project Name**: ogguf
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-26
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ogguf — ROCm HIP LLM Inference Serving Platform

[中文](#中文) | [English](#english)

---

## 中文

**Ogguf** 是一个 LLM 推理服务平台，专为 AMD ROCm HIP 加速器设计。服务层使用 Rust 编写，推理内核通过 [llama.cpp](https://github.com/ggerganov/llama.cpp) 的 HIP 后端动态 FFI 调用。

### 核心特性

- ✅ **OpenAI/Anthropic/Gemini/Responses API 兼容**: completions / chat / messages / responses / gemini / embeddings / rerank / models / health / metrics / admin 全端点可用
- ✅ **ogguf.json 统一 per-model 配置中心**: 每个模型自动构建独立的 `ogguf.json`，持久化全部元数据（聊天模板 / 工具调用格式 / 思考标签 / 特殊标签 / 视觉元数据 / 辅助模型 / 采样参数），各端点统一复用，**替代手工编码的模型家族表**
- ✅ **定时扫描零重构**: 定时扫描模型目录，已有 `ogguf.json` 只读不刷新；仅新模型（无 ogguf.json）才自动构建
- ✅ **手动重建入口**: CLI `ogguf rebuild <id|all>` + API `POST /v1/models/{id}/rebuild` + Admin Dashboard 每模型"重建"按钮
- ✅ **视觉理解 (VLM)**: 通过 mmproj 辅助 GGUF 自动检测视觉能力，支持 OpenAI image_url 格式，注入 vision 标记对齐 embeddings
- ✅ **智能模型发现**: GGUF 元数据解析、模型类型识别（LLM/MoE/VLM/Embedding/Reranker/TTS/OCR/MTP）、tool calling 格式从聊天模板自动检测
- ✅ **流式输出**: SSE 流式生成，含 finish_reason + usage stats；thinking 内容按 Anthropic API 规范 opt-in（`body.thinking`）
- ✅ **并发批处理**: Semaphore 限流并发
- ✅ **Paged KV Cache**: 块表 (BlockTable) + 物理块池 + CoW 前缀共享
- ✅ **采样控制**: temperature / top_p / seed / presence_penalty / frequency_penalty / stop / n / logprobs
- ✅ **内存准入防护**: 冷加载前检查 GPU 内存预算，超限先 LRU 驱逐非 pinned 模型，仍超则返回 HTTP 507 而非 OOM 崩溃
- ✅ **Admin Dashboard**: 模型列表 + 流式 Chat + 设置面板 + Pin/Unpin + 重建
- ✅ **内存管控**: 系统 RAM + GPU VRAM 监控 (sysfs)，自动驱逐
- ✅ **配置系统**: TOML 文件 + 环境变量 + **per-model ogguf.json 三级覆盖**（请求体 > 模型配置 > 全局配置）
- ✅ **生产就绪**: API Key 鉴权 + CORS + 请求体验证 + 速率限制 (Token Bucket)
- ✅ **可观测性**: `/health`、`/metrics` (Prometheus)、`tracing` 结构化日志
- ✅ **APU 统一内存优化**: 部署脚本持久化 TTM pages_limit（0.95×RAM），HIP/llama.cpp 可见全量 GTT

### API 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/models` | GET | 模型列表（类型、家族、量化、视觉、加载状态） |
| `/v1/models/{id}/settings` | GET/POST/DELETE | 模型设置 CRUD（持久化到 ogguf.json） |
| `/v1/models/{id}/rebuild` | POST | 强制重建该模型的 ogguf.json |
| `/v1/models/{id}/load` / `unload` | POST | 加载 / 卸载模型 |
| `/v1/models/{id}/pin` / `unpin` | POST | Pin 模型 (防 LRU 驱逐) |
| `/v1/models/rescan` | POST | 手动触发目录扫描 |
| `/v1/completions` | POST | OpenAI 文本补全 |
| `/v1/chat/completions` | POST | OpenAI Chat（SSE 流式 + 非流式 + tools） |
| `/v1/messages` | POST | Anthropic Messages API（SSE 流式 + 非流式 + tools + thinking opt-in） |
| `/v1/responses` | POST | OpenAI Responses API（+ tools） |
| `/v1beta/models/{model}:generateContent` | POST | Gemini API（+ tools） |
| `/v1/embeddings` | POST | 文本向量化（pooling 自动配置） |
| `/v1/rerank` | POST | 余弦相似度重排 |
| `/v1/models/downloader/*` | GET/POST | HuggingFace / ModelScope 模型下载 |
| `/health` / `/metrics` | GET | 健康检查 / Prometheus 指标 |
| `/admin` | GET | 管理后台 Dashboard |

### 架构概览

```
Actix-web API Server (18+ routes, auth/CORS/rate-limit)
         ↓
   Engine Pool (LRU, pinning, TTL, 内存准入)
         ↓
   Batch Scheduler (Semaphore concurrent)
         ↓
   Inference Engine (采样、thinking 追踪、工具调用解析)
         ↓
   Paged KV Cache (BlockTable + PhysicalBlockPool + CoW)
         ↓
   llama.cpp HIP Backend (libloading FFI) + libmtmd (视觉)
         ↓
   ROCm GPU Kernels
```

### 配置架构：ogguf.json 统一 per-model 配置中心

每个模型目录自动生成唯一的 `ogguf.json`，作为该模型**唯一的可编辑配置源**：

```json
{
  "model_id": "Qwen3.6-35b-a3b-8bit-mtp",
  "path": ".../Qwen3.6-35B-A3B-Q8_0.gguf",
  "architecture": "qwen35moe",
  "family": "qwen3.5",
  "model_type": "vlm",
  "ctx_len": 262144,
  "quant": "Q8_0",
  "tool_format": "xml",
  "chat_template": "{...完整聊天模板...}",
  "think_level": "medium",
  "thinking_tags": ["<think>", "</think>"],
  "special_tags": ["<|im_start|>", "<|vision_start|>", "<tool_call>", ...37个...],
  "vision_markers": ["<|vision_start|>", "<|image_pad|>", "<|vision_end|>"],
  "vision_image_size": 768,
  "vision_n_embd": 1152,
  "mmproj_path": ".../mmproj-BF16.gguf",
  "params": {"temperature": 0.7, "top_p": 0.9, "kv_cache_type": 1, "nextn_predict_layers": 1, ...},
  "aux_files": [
    {"kind": "mmproj", "path": "...", "metadata": {"clip.vision.image_size": "768", ...}},
    {"kind": "json-config", "path": "..."},
    {"kind": "readme", "path": "..."}
  ],
  "settings": null
}
```

**生命周期规则**：

| 场景 | 行为 |
|------|------|
| 定时扫描 | 已有 ogguf.json **只读不刷新** |
| 新模型（无 ogguf.json） | 自动完整构建 |
| 手动重建（CLI/API/前端按钮） | 全量重新读取 GGUF 元数据，**保留用户 settings** |
| 前端参数配置（/settings） | 持久化到 ogguf.json 的 `settings` 段 |

**构建时完整扫描**：读取主模型 GGUF 头 + 目录内所有辅助文件（mmproj/TTS/OCR/configuration.json/README），提取聊天模板、工具格式、特殊标签、MTP 参数、视觉元数据等。

**三级参数覆盖**：请求体 > per-model ogguf.json params > 全局 TOML 配置。

**特殊标签提取**：从 `tokenizer.ggml.tokens` + `token_type`（CONTROL/USER_DEFINED）+ 显式特殊 token + 聊天模板引用，完整提取模型的特殊标签（视觉/工具/思考/TTS/FIM 等），推理时用于智能过滤与判定。

### 快速开始

```bash
# 构建
cargo build --release

# CLI serve（自动扫描模型目录，构建各模型 ogguf.json）
cargo run -p cli -- serve --model-dir /path/to/models --port 8080

# 或直接启动 api_server
cargo run -p api_server -- --model-dir /path/to/models

# 单模型测试
cargo run -p minimal -- --model-path /path/to/model.gguf "Hello"
```

```bash
# API 使用示例
curl http://localhost:8080/v1/models

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"model-name","messages":[{"role":"user","content":"Hi"}],"stream":true,"temperature":0.7}'

# 视觉理解 (VLM)
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"vlm-model","messages":[{"role":"user","content":[
    {"type":"text","text":"分析这张图"},
    {"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}
  ]}]}'

# 工具调用 (tools)
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"model-name","messages":[{"role":"user","content":"用工具算 2+2"}],
       "tools":[{"type":"function","function":{"name":"add","description":"加法","parameters":{"type":"object","properties":{"a":{"type":"number"},"b":{"type":"number"}}}}}]}'

curl http://localhost:8080/health
```

### CLI 命令

```bash
ogguf start   # 启动服务（含 watchdog 自动重启）
ogguf stop    # 停止服务
ogguf status  # 服务状态
ogguf list    # 列出所有已注册模型
ogguf rebuild <id|all>   # 强制重建模型 ogguf.json（从 GGUF 重新解析）
ogguf add-dir <dir>      # 添加模型扫描目录
ogguf update             # 更新 + 重新编译 + 部署 + 重启
ogguf version            # 版本号
```

### 配置

**全局 TOML** (`~/.ogguf-venv/etc/ogguf.toml`):

```toml
default_ctx_len = 200000

[backend]
selected = "hip"  # "hip" | "vulkan" | "cpu"

[models]
directory = "/mnt/data/llm"
discovery = true

[generation]
max_tokens_ceiling = 8192
default_temperature = 0.3

[gtt]
enabled = true
size_gb = 113
```

**环境变量**:

| 变量 | 说明 |
|------|------|
| `OGGUF_HOME` | 部署根目录（默认 `~/.ogguf-venv`） |
| `OGGUF_BACKEND` | 后端: hip / vulkan / cpu |
| `OGGUF_LIB_DIR` | llama.cpp 动态库目录 |
| `OGGUF_CONFIG` | 配置文件路径 |
| `OGGUF_API_KEY` | API 鉴权密钥 (Bearer Token) |
| `OGGUF_N_BATCH` / `OGGUF_N_UBATCH` | 批处理大小 |
| `TOKEN_SCALE_FACTOR` | Token 计数缩放 (Claude Code) |

### 部署

**首次部署**（安装 ROCm + 编译 llama.cpp + 构建项目 + 配置 GTT/TTM）：
```bash
./scripts/deploy_hip.sh
```

**已安装 ROCm 仅重编译**：
```bash
./scripts/deploy_hip.sh --skip-rocm
```

部署完成后 CLI 自动注册到系统，之后更新只需：
```bash
ogguf update
```

**APU 统一内存**：部署脚本自动持久化 `amdgpu gttsize` 和 `ttm pages_limit`（0.95×RAM），让 HIP/llama.cpp 可见全量 GTT。

### Admin Dashboard

访问 `http://localhost:8080/admin`:
- 模型列表（ID / 家族 / 类型 / 量化 / 视觉 / 加载状态）+ Pin/Unpin/Load/Unload/**Rebuild**/Settings
- 流式 Chat 界面（temperature 滑块 + streaming toggle）
- 模型设置面板（Temperature / Top-P / Alias / TTL，持久化到 ogguf.json）
- 模型下载（HuggingFace / ModelScope）

### 项目结构

```
ogguf/
├── crates/
│   ├── api_server/        # Actix-web HTTP 服务 (18+ routes, SSE, auth, CORS)
│   ├── engine/            # 推理引擎 (采样、调度、KV 缓存、FFI、VLM 视觉)
│   ├── engine_pool/       # 引擎池 (LRU, pinning, TTL, 内存准入)
│   ├── memory_enforcer/   # 内存监控与驱逐
│   ├── model_discovery/   # 模型扫描、ogguf.json 构建、HF/ModelScope 下载
│   ├── model_settings/    # 模型配置持久化 (sled + ogguf.json)
│   ├── admin_dashboard/   # 管理后台 HTML
│   ├── cli/               # CLI (serve/rebuild/update 等)
│   └── minimal/           # 最小示例
├── scripts/
│   ├── deploy_hip.sh      # 部署脚本（含 GTT/TTM 配置）
│   └── validate_hip.sh    # HIP 环境验证
└── docs/                  # 文档
```

### 开发状态

| 模块 | 状态 | 注 |
|------|------|-----|
| API 端点 | ✅ | 18+ 全可用 |
| 流式输出 | ✅ | SSE + thinking opt-in |
| 采样 | ✅ | temperature/top_p/seed/penalties/stop/n/logprobs |
| 并发调度 | ✅ | Semaphore |
| KV Cache | ✅ | BlockTable + PhysicalPool + CoW |
| 引擎池 | ✅ | LRU + pinning + TTL + 内存准入 |
| **ogguf.json 配置中心** | ✅ | 元数据 + 模板 + 标签 + 参数统一管理 |
| **视觉理解 (VLM)** | ✅ | mmproj 自动检测 + 视觉标记对齐 |
| Embedding/Rerank | ✅ | pooling 自动配置 |
| 工具调用 | ✅ | 模板驱动 (xml/json) |
| Admin | ✅ | 模型管理 + 重建 + 设置 |
| MCP | 🚧 | 计划中 |

### 测试

```bash
cargo test --workspace          # 全部测试通过
cargo check --workspace         # compiles clean
cargo clippy --workspace        # lint
```

### 故障排查

**HIP 后端未找到**: 确保 `OGGUF_LIB_DIR` 指向编译好的 llama.cpp 目录，包含 `libllama_hip.so`。

**GPU 内存不足**: ogguf 冷加载前自动做准入检查（HTTP 507），或调大上下文/使用更小量化模型。

**VLM 视觉不工作**: 确认模型目录含 `mmproj` 辅助文件，`ogguf rebuild <id>` 后 `vision_markers`/`mmproj_path` 正确。

**Claude Code 无回复**: 确认服务运行 (`ogguf status`)，Anthropic thinking 按 `body.thinking` opt-in，未请求时输出 text_delta。

### 相关文档

| 文档 | 说明 |
|------|------|
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 架构文档 |
| [API.md](docs/API.md) | API 参考 |
| [DEPLOYMENT.md](docs/deploy/DEPLOYMENT.md) | 部署指南 |
| [HIP_SETUP.md](docs/HIP_SETUP.md) | HIP 环境配置 |
| [TESTING.md](docs/TESTING.md) | 测试指南 |
| [test-report-v0.7.1-stress.md](docs/test/test-report-v0.7.1-stress.md) | 端到端压力测试报告 |

### 许可证

Apache 2.0。

### 致谢

- [OMLX](https://github.com/jundot/omlx) — 架构参考与功能对标
- [llama.cpp](https://github.com/ggerganov/llama.cpp) — HIP 推理内核
- [Actix-web](https://actix.rs/) — 高性能 HTTP 框架
- [Tokio](https://tokio.rs/) — 异步运行时

---

## English

**Ogguf** is an LLM inference serving platform targeting AMD ROCm HIP accelerators. The service layer is written in Rust, and inference kernels are invoked via the [llama.cpp](https://github.com/ggerganov/llama.cpp) HIP backend through dynamic FFI loading.

### Key Features

- ✅ **Multi-API compatible**: OpenAI / Anthropic / Gemini / Responses / embeddings / rerank
- ✅ **ogguf.json per-model config center**: each model gets an auto-built `ogguf.json` persisting chat template, tool format, thinking/special tags, vision metadata, aux models and sampling params — replacing the hand-coded family table
- ✅ **Zero-rebuild scans**: periodic directory scans never rewrite existing `ogguf.json`; only new models get built
- ✅ **Manual rebuild entrypoints**: CLI `ogguf rebuild <id|all>`, API `POST /v1/models/{id}/rebuild`, Admin button
- ✅ **VLM vision understanding**: auto-detects mmproj, OpenAI image_url format, vision-marker alignment
- ✅ **SSE streaming**: with finish_reason + usage stats; thinking is opt-in per Anthropic spec
- ✅ **Memory admission control**: pre-load GPU budget check, LRU eviction, HTTP 507 instead of OOM crash
- ✅ **Paged KV Cache**: BlockTable + PhysicalBlockPool + CoW prefix sharing
- ✅ **Admin Dashboard**: model management + rebuild + settings
- ✅ **APU unified memory**: deploy script persists TTM pages_limit for full GTT visibility

### Quick Start

```bash
cargo build --release
cargo run -p cli -- serve --model-dir /path/to/models
```

### CLI

```bash
ogguf start|stop|status|list|rebuild <id|all>|update|version
```

### Configuration

Global TOML + env vars + per-model ogguf.json three-level override (request > model config > global).

### Testing

```bash
cargo test --workspace
```

### License

Apache 2.0.

### Acknowledgments

- [OMLX](https://github.com/jundot/omlx) — architectural reference
- [llama.cpp](https://github.com/ggerganov/llama.cpp) — HIP inference kernels
- [Actix-web](https://actix.rs/) — HTTP framework
- [Tokio](https://tokio.rs/) — async runtime