内容
<h1 align="center">llama-vulkan-strix</h1>
<p align="center">
<strong>llama.cpp OpenAI兼容服务器，基于Vulkan后端，用于在AMD Strix Halo APU（gfx1151）上测试GGUF模型。权重加载到GTT（统一内存），而不是小VRAM划分，并且有一个脚本来证明这一点。可选的无密钥网页搜索MCP侧车。</strong>
</p>
<p align="center">
<img src="https://img.shields.io/badge/AMD-Strix_Halo-ED1C24?logo=amd&logoColor=white" alt="AMD Strix Halo" />
<img src="https://img.shields.io/badge/backend-Vulkan-AC162C?logo=vulkan&logoColor=white" alt="Vulkan" />
<img src="https://img.shields.io/badge/llama.cpp-server-000000" alt="llama.cpp" />
<img src="https://img.shields.io/badge/License-MIT-blue" alt="License" />
</p>
---
## 这是什么
一个围绕预构建的`ghcr.io/ggml-org/llama.cpp:server-vulkan`镜像的精简Docker Compose包装器。将其指向一个GGUF文件文件夹，在`.env`中设置一个，启动它，您就拥有了一个OpenAI兼容的端点，位于`:8080`。在`.env`中交换模型并重新启动以测试下一个。
无需ROCm，无需`/dev/kfd`，无需特权容器。Vulkan后端只需要`/dev/dri`和您的GPU组ID。它不构建任何内容：基础堆栈是一个单独的拉取镜像。
## 快速开始
前提条件：一台AMD Strix Halo盒子（Ryzen AI Max+，gfx1151），最近的amdgpu内核，Docker + Compose，以及磁盘上的一些GGUF模型。
```bash
cp .env.example .env
# 编辑.env：设置MODELS_DIR、LLM_MODEL和您的RENDER_GID / VIDEO_GID
# getent group render | cut -d: -f3
# getent group video | cut -d: -f3
docker compose up -d
docker compose logs -f llm # 观察它加载
```
调用它：
```bash
curl http://localhost:8080/v1/chat/completions \
-H 'content-type: application/json' \
-d '{"model":"llm","messages":[{"role":"user","content":"hi"}]}'
```
测试不同的模型：编辑`.env`中的`LLM_MODEL`，然后再次执行`docker compose up -d`。
## GTT，而不是VRAM
在Strix Halo上，专用的“VRAM”是一个小的BIOS划分；128 GB的统一内存可以通过GTT被GPU访问。你希望模型权重在GTT中，VRAM接近空闲。
Compose文件在服务器上设置`GGML_VK_PREFER_HOST_MEMORY=1`。在llama.cpp的Vulkan后端，这是一个存在检查（任何值都启用它），它使分配器首先请求主机可见的/GTT内存，只有在VRAM作为备用时。在gfx1151上，后端是UMA，并且已经默认优先使用GTT；设置它使之明确和保证。
在模型加载后证明这一点：
```bash
scripts/verify-gtt.sh --min-gtt-mib 14000 # ~14 GB模型；调整为您自己的
```
它等待 `/health`，然后读取内核的amdgpu计数器下的 `/sys/class/drm/card*/device/` (`mem_info_gtt_used`，`mem_info_vram_used`，以字节为单位），并断言GTT承载负载，而VRAM保持空闲。`scripts/gpu_mem.py`是底层工具（ `--json` 获取原始快照）。这些sysfs计数器是在Strix Halo上真相的来源，其中 `rocm-smi` 可以针对小VRAM池进行错误报告。 `amdgpu_top` 和 `radeontop` 显示相同的分割实时。
## 网页搜索（可选）
一个可选的侧车运行 [hec-ovi/websearch-skill](https://github.com/hec-ovi/websearch-skill) （无密钥网页搜索 + 页面获取以清理Markdown）作为MCP服务器通过HTTP，因此您可以测试模型或任何MCP客户端，可以调用 `web_search` / `web_fetch` 作为工具。
```bash
docker compose --profile tools up -d
# MCP端点（流式HTTP）：http://localhost:8000/mcp
```
将MCP客户端指向该URL。工具： `web_search` ， `web_fetch` ， `web_open` ， `arxiv_search` ， `github_search` 。
捆绑的 `websearch mcp` 命令仅支持_stdio ； `tools/websearch_http.py` 将相同的FastMCP服务器翻转为HTTP，以便通过网络访问。如果您根本不需要侧车，请直接调用它：
```bash
uvx --from git+https://github.com/hec-ovi/websearch-skill websearch web-search "your query" --json
```
## 布局
```text
docker-compose.yml llm服务（+可选的网页搜索侧车）
.env.example 模型，端口，GPU组ID
scripts/gpu_mem.py 读取amdgpu VRAM与GTT计数器； --verify模式
scripts/verify-gtt.sh 等待/health，然后断言模型在GTT中
tools/websearch_http.py 网页搜索MCP服务器通过HTTP（侧车入口点）
tools/Dockerfile.websearch 侧车镜像（仅使用--profile tools构建）
tests/ compose不变量，gpu_mem解析器，包装器
```
## 许可证
[MIT](LICENSE) 适用于这里的构建胶水。此仓库拉取预构建的镜像并以只读方式安装您的模型；llama.cpp是MIT许可证，GGUF权重您安装的权重具有其自己的许可证（Gemma，Llama，Qwen等）。您有责任遵守每个模型的条款。
