AMD 显卡跑通 MiniMax-H3 视频全家桶：ZLUDA + GGUF Q4_K 完整实录

8GB 显存的 AMD 显卡，能不能跑一个原始体积 41GB 的文生视频/图生视频/音视频联合生成模型？
答案是：能，而且我已经跑通了。这篇记录我踩过的每一个坑。

📖 前言

MiniMax-H3 是支持文本生成视频（t2va）、首尾帧生成视频（ref2va）、图像生成视频（fl2va）三合一的音视频联合生成模型，权重高达 41GB。正常来说这是 24GB 显存显卡的玩具。

但我手里只有一张 AMD RX 6650 XT（8GB 显存），还吃不到 CUDA 生态——只能靠 ZLUDA 翻译层把 CUDA 调用翻译成 AMD 的 HIP。整个过程中我换了两次技术方案、打了 8 个补丁、排了 14 轮错，最终用 GGUF Q4_K 量化把模型压到 10.6GB，成功跑进采样循环。

这篇文章是完整的操作记录和排错路线图，希望能帮你少走弯路。

🎯 最终方案

核心逻辑：Q4_K 权重只有 int8 版的一半，主模型能塞进 8GB 显存，配合 lowvram 模式逐层搬运，就能完整跑起来。

🧱 方案选型：为什么抛弃 int8 转投 GGUF

第一版方案用 int8 量化版（20.97GB），forward 时显存峰值 10.6GB，超过 8GB 物理显存，必死。

💡 结论：8GB 显存想跑大视频模型，量化率必须到 Q4 级别，int8 只是减半，不够。

📦 模型与文件清单

下载技巧：HuggingFace 直连在国内基本不可用，换 hf-mirror.com 镜像（实测速度 35MB/s）。下载完务必确认文件大小与仓库标注一致，不要留 .part 残留。

🔧 前置补丁：让 ComfyUI 在 ZLUDA 上活下来

ZLUDA 环境下有 5 个补丁是缺一不可的，不补的话报错会随机出现在任何地方（因为 CUDA 上下文从启动起就坏了）。

⚠️ 最大的认知坑：ZLUDA 伪造算力

ZLUDA 会让 torch.cuda.get_device_capability() 返回 (8, 8)——假装自己是 RTX 40 系！这导致 PyTorch 启用所有原生 CUDA kernel，而实际后端是 HIP，全部崩溃。

必须主动压制算力检测，强制所有”是否支持快速算子”的判断走降级路径。这是前几轮所有诡异报错的共同根源。

🐛 GGUF 专属巨坑：BF16 反序列化（本文最值钱的部分）

症状（采样第 1 步必现）：

1
2

NoCapableBackendError: rms_rope_split_half_:
eager: q_scale: dtype torch.uint8 not in {bfloat16, float32, float16}

排查过程：

1. 报错在 Attention 的”融合 RMSNorm + RoPE”算子，参数 q_scale 是 RMSNorm 权重
2. 查 GGUF 文件头：q_norm.weight 在 GGUF 里明明是 BF16 类型
3. 为什么运行时变成 uint8？→ 打开 GGUF 加载器源码，真相大白

根因：GGUF 文件里 BF16 张量按 2 字节 uint16 小端存储，而 numpy 没有 bfloat16 类型，所以 GGUFReader 把它暴露为 uint8 原始字节。加载器只对 F32/F16 做了 reshape，漏掉了 BF16 分支——于是全模型 212 个 BF16 张量（RMSNorm 权重等）以 uint8 裸字节喂给了模型。

修复（加载器内加一个分支）：

1
2
3
4

if tensor.tensor_type == BF16:
    torch_tensor = torch_tensor.view(torch.uint16).view(torch.bfloat16).view(*shape)
elif tensor.tensor_type in {F32, F16}:
    torch_tensor = torch_tensor.view(*shape)

验证：修复后 q_norm.weight 应为 bfloat16、形状正确、数值均值≈1（RMSNorm 权重特性）。

💡 这是所有含 BF16 张量的 GGUF 的通用 bug，不是 MiniMax 专属。如果你的 GGUF 加载后各种 dtype 报错，先检查这一处。

🧩 工作流搭建：魔改版节点的坑

运行时报”缺失节点包”，但节点明明装了——排查后发现：

• 第三方整合包预装的 ComfyUI-GGUF 是魔改版，节点名是 LoaderGGUF、输入字段叫 gguf_name
• 官方版本（city96）的节点名是 UnetLoaderGGUF、字段 unet_name
• 工作流引用官方节点名 → 前端报缺失

教训：报”缺失节点包”先查运行中实例的 /object_info 接口，看实际注册的类名，再决定是改工作流还是装包，别急着装 Node Manager。

完整工作流关键节点：

🗺️ 排错路线图（判断补丁是否生效的标尺）

14 轮排错中，报错不是随机的——它按固定轨迹演进，每前进一格说明前面的补丁生效了：

1
2
3
4
5

operation not supported              ← CUDA 上下文已坏（最早期，补丁 1-4 前）
shared object initialization failed  ← 物理内存枯竭（页面文件不够）
out of memory (10.6GB > 8GB)         ← 显存物理极限（int8 方案的死因）
q_scale dtype uint8                  ← GGUF BF16 反序列化（补丁 6 解决）
正常采样循环                          ← ✅ 全链路打通

💾 内存与性能管理

• 32GB 物理内存是极限：编码器 15GB + 主模型 offload 5GB + 各类对象，运行期间必须关掉其他大程序
• 页面文件扩到独立盘符（系统盘放不下），48GB 起步
• 崩溃后必查残留进程：python.exe 可能残留占 20GB+ 内存，清掉再重启

🔊 番外：能出画面，但为什么没声音？

跑通后我兴冲冲打开视频——画面正常，但一点声音都没有。这是 H3 最容易踩的静默失败：不报错，就是没音轨。

根因一：视频和音频是两套独立 VAE

MiniMax H3 的”音视频联合生成”指的是采样过程联合，但解码阶段两套 VAE 完全分开：

官方仓库两个文件分开提供，我一开始只下了视频 VAE——根本没音频解码器，当然没声音。

根因二：音频 latent 被静默丢弃

采样器输出的 latent 是个嵌套张量对：

1

NestedTensor( video[B,24,T,H/16,W/16] , audio[B,32,2,T40] )

普通的 VAEDecode 只解 video，audio 分支被直接扔掉，而且不报任何错。合流节点 CreateVideo 的 audio 输入空着，出来的自然是哑巴视频。

解法：通用音频解码节点就够

一开始我以为要装 MiniMax 专属音频节点，翻源码才发现 ComfyUI 的通用节点 VAEDecodeAudio 内部已经处理了嵌套张量：

1
2
3

latent = samples["samples"]
if latent.is_nested:
    latent = latent.unbind()[-1]   # 取最后一个 = audio

所以工作流加两个节点就行：

💡 避坑提示：音频 VAE 的识别键是 pre_block.attn.zero_k_bias（ComfyUI 靠它判断是不是 H3 音频 VAE）。下载后建议验证一下这个键存在，同时确认没有 decoder.model.0.weight_g——否则会被误判成 MiniMax Music3 的 DAV 模型。

⚡ 番外二：4 步加速 LoRA，与”静默失效”这个隐形杀手

10 步采样在 ZLUDA 上太慢，于是加上官方的 4 步 turbo LoRA（1.87GB）。本以为只是拖个节点的事，结果又踩了两个坑——其中一个不会报任何错。

坑一：768p 版的 shift 是 6/3，不是 12/3

同一个仓库里挂着好几个 turbo LoRA，超参并不通用。官方规格表：

只看”几步”去抄参数是错的，必须同时核对版本和分辨率两列。基础版工作流用的 shift 是 12/3，换上 768p 的 LoRA 后必须改成 6/3，否则 sigma 网格对不上蒸馏时学到的轨迹，步数再少也白搭。

坑二：LoRA 加载失败是静默的

这是本文第二个”最值钱”的坑。

给模型挂上 LoRA，点 Queue，没有任何报错，视频照常生成，进度条照常走完——但速度和画质一点没变。LoRA 根本没生效。

原因出在键名前缀：

1
2

主模型 state_dict :  blocks.0.attn.qkv_proj.weight            ← 无前缀
官方 turbo LoRA   :  diffusion_model.blocks.0.attn.qkv_proj   ← 有 diffusion_model. 前缀

ComfyUI 的 comfy/lora.py 里，model_lora_keys_unet() 给 Flux、SD3、Kandinsky5、LTXV、QwenImage 等每个架构单独写了一段键名映射——但 MiniMax H3 是新增架构，还没有它的分支，于是只能落到”无前缀”的通用映射上，命中率 0 / 208。

而 load_lora_for_models() 匹配不到键时，只会在日志里打一行 lora key not loaded，然后继续正常执行。生成结果完全合法，只是 LoRA 的贡献为零——白占 1.87GB 显存和几十秒加载时间。

怎么验证：不需要真去加载 10GB 模型，纯静态比对键名即可。

1
2
3
4
5
6

# sd_keys 取自 GGUF 的 tensor 名；mods 取自 LoRA 的 lora_A/lora_B 键去后缀
key_map = {k[:-len(".weight")]: k for k in sd_keys}   # 通用映射（补丁前）
# → MATCHED: 0     MISSING: 208

key_map["diffusion_model." + k[:-7]] = k              # 补上前缀映射
# → MATCHED: 208   MISSING: 0     ✅

怎么修：在 comfy/lora.py 的 return key_map 之前加一段：

1
2
3
4
5
6

if isinstance(model, comfy.model_base.MiniMaxH3):
    for k in sdk:
        if k.endswith(".weight"):
            key_lora = k[:-len(".weight")]
            key_map["diffusion_model.{}".format(key_lora)] = k
            key_map["transformer.{}".format(key_lora)] = k

⚠️ 改的是核心文件，必须重启 ComfyUI 才生效。重启后跑一次，日志里不应再出现 lora key not loaded。

顺带一提，这个 LoRA 用的是 PEFT 命名（lora_A.weight / lora_B.weight），不是 ComfyUI 常见的 lora_up / lora_down。这个是没问题的——ComfyUI 的 weight_adapter 已经内置了 diffusers2 分支来处理它。

参数对照

注意 LoRA 必须插在 SigmaShift 之前。

另外两个小知识

GGUF 量化模型叠 LoRA 会不会爆显存？ 不会。ComfyUI-GGUF 对量化权重走的是延迟 patch：保持量化状态，把 patch 挂上去，等到真正 forward 时才逐层反量化合并——不会一次性把 10GB 模型展开成 bf16。对 8GB 显卡相当友好。

帧数不是随便填的。 官方工作流用 max(5, round(a*24)) + (5 - (max(5, round(a*24)) % 17)) % 17 来对齐帧数，等价于要求 length % 17 == 5（H3 的时间维压缩对齐）。124 帧正好合规（124 = 7×17 + 5）。

已知取舍

• turbo 模式下音频与运动质量略低于全步数版本（ComfyUI 官方文档口径）。
• LoRA 训练分辨率是 768p（1344×768），若实际跑 480p 则低于原生画布，画质增益会打折。
• 显存吃紧时，把 cfg 降到 1.0 可以再省掉一半前向计算（负向不再参与）。

🔮 下一步

• 480P 5 秒视频跑通
• 音频链路修复（音频 VAE + 通用音频解码节点，见上节）
• 4 步 turbo LoRA 就位（含键名前缀补丁，见上节）
• 验证音画同步与音质
• 验证 4 步加速的实际提速倍数与画质变化
• 测 t2va（纯文本）与 ref2va（首尾帧）变体
• 摸底 8GB 显存能扛的最大分辨率/帧数

📝 写在最后

整个过程最大的体会：AMD 跑 AI 不是不行，是坑多。ZLUDA 伪造算力、分配器不兼容、GGUF 反序列化漏分支……每一个都是”看起来像玄学、查下去全是逻辑”的问题。

如果你也是 AMD 用户想跑大模型，记住三句话：

1. 显存不够就上 Q4 量化，int8 只是减半，不够
2. 报错随机 ≠ 问题随机，先查 CUDA 上下文是否健康
3. GGUF 的 BF16 张量，十有八九是反序列化问题

祝你也跑通 🎉

比较简单，打发时间的小品游戏。很适合后台挂个AI干活的时候玩。

dsh-model-fix

修复特定模型在 DeepSeek Harness（DSH）里「流式内容正常但回合必报错」的流式收尾缺陷。

本仓库是 bitterSmilezzz/dsh-model-fix 的增强版：
在原版（muse-spark-1.2）基础上，加入了对 gpt-5.6-luna 的支持（同一缺陷，实测
2026-08-23：gpt-5.6-luna 流式/非流式响应的 finish_reason 均为 null，且流式不发 [DONE]）。

背景：缺陷根因

opencode 聚合端点（https://opencode.ai/zen/go/v1）上的 muse-spark-1.2 与
gpt-5.6-luna 实现有缺陷：流式响应正常吐出内容，但从不发送 finish_reason、也不发送
[DONE]，流直接关闭（同端点对照 deepseek-v4-flash / glm-5.2 均正常发送
finish_reason: 'stop' + [DONE]）。

DSH 的 llm-pi-ai 走 pi-ai SDK（强制 stream: true 且要求流以 finish_reason 收尾），
于是每次对话的真实表现是：

1. 内容正常流式显示；
2. 结尾报 Stream ended without finish_reason（映射为 TRANSPORT 错误）；
3. 回合被判失败，且 TRANSPORT 在默认可重试列表里 → agent 级重试插件按
   maxRetries 反复重跑整步，烧多份 token。

这与代理无关：直连与走代理的响应完全相同，换代理解决不了。

⚠️ 重要说明：无需开启 opencode 的「Allow models that train on request data」

使用 muse-spark-1.2 / gpt-5.6-luna（经 opencode-go 路由）不需要在 opencode 平台设置里
开启**「Allow models that train on request data」**。

• 该开关是 opencode 的数据训练授权：开启后你的请求数据可能被用于模型训练，属于
  需要慎重对待的隐私授权，不要为了使用这些模型而开启它；
• 实测：不开启该开关，直连 https://opencode.ai/zen/go/v1 即可正常
  返回内容（本插件修复的只是流式收尾缺陷，与训练授权无关）；
• 若在 opencode 设置里看到该开关，保持关闭即可；本文档所述修复不依赖它。

开关位置见下图（opencode 设置页 → 提供商区域，与「启用部署在中国的模型」相邻）：

本插件做什么

在 llm/stream waterfall 上，对匹配的模型把上述缺陷收尾为正常 stop：

• 仅当流已输出内容（text-delta / reasoning-delta / tool-call-delta）且
  结尾错误代码为 TRANSPORT / STREAM_CLOSED 且错误信息明确是「缺少终止事件」
  （如 Stream ended without finish_reason）时才改写；
• 真实传输故障（如 SocketError: other side closed）不受影响，照常失败；
• 无内容的空响应也照常失败，不会被误吞。

修复后 muse-spark-1.2 / gpt-5.6-luna 直连即可正常使用，无需代理、不触发重试。

安装

1
2
3
4
5

# 从 GitHub 安装（推荐）
npx -y @deepseek-ai/dsh plugin --profile web add github:Retr67/dsh-model-fix

# 本地路径
# dsh plugin --profile web add /path/to/dsh-model-fix

安装后重启目标 profile（如 dsh web）生效。

配置

cordis.patch.yml 中 config 两个字段：

1
2
3
4
5

- id: model-fix
  name: dsh-model-fix
  config:
    modelPattern: '^(muse-spark|gpt-5\.6-luna)'
    providers: []

只修 luna 可改为 modelPattern: '^gpt-5\.6-luna'；只想限定某个路由可加
providers: [ 'opencode-go' ]。

开发

1
2

pnpm install
pnpm verify    # typecheck + build + node --test

验证矩阵

• 单元测试：tests/fix.test.mjs 覆盖缺陷识别、内容保留、空响应放行、真实故障放行等 10 例。
• 真实端点集成验证：用 pi-ai 同款 SDK 直连 muse-spark-1.2 / gpt-5.6-luna，内容经本插件转换后
  结尾由 error(Stream ended without finish_reason) 变为 {"kind":"stop"}。

致谢

• 上游：bitterSmilezzz/dsh-model-fix（MIT）
• 缺陷取证（gpt-5.6-luna）：2026-08-23 直连 opencode.ai/zen/go/v1 复现——流式 10 个 chunk
  中 finish_reason 全程 null、无 [DONE]，尾部为 data: {"choices":[],"cost":"0"}；
  非流式响应 finish_reason 同样为 null。

dsh-plugin-manager

DeepSeek Harness (DSH) 插件管理器：在 WebUI 设置 → 插件 → 插件管理 里可视化查看、临时打开、关闭其他插件。

• 用户插件（可开关）：你在 profile/package.json 里安装的社区插件 + 你自己在 cordis.patch.yml 里加的条目（如 MCP 桥梁）。
• 系统组件（只读）：DSH 自带的 host/web 基础设施，只展示、不提供开关，避免误关导致 Harness 起不来。
• 开关无需重启 dsh：走的是 Cordis loader 的 entry.update({ disabled })（与官方 dsh-market 主题开关同一条路）。默认在切换后自动刷新网页，让带前端界面的插件（桌宠、侧边栏等）也立即完全生效；也可在面板里切到手动刷新模式（选择保存在浏览器 localStorage）。
• 跨重启保持：被关闭的插件 id 会记在 <profile>/.plugin-manager/state.json，下次启动时自动回放为关闭，直到你把它打开。
• 「全部恢复开启」按钮一键清空所有保持关闭的插件。

环境要求

• DeepSeek Harness (dsh)
• Node.js（含 npx）
• Windows / macOS / Linux 均可

安装（一行命令）

在任意终端执行（默认安装到 web profile）：

1

npx -y @deepseek-ai/dsh plugin --profile web add https://github.com/Retr67/dsh-plugin-manager.git

该命令会：① 安装依赖；② 检测到包声明了 dsh.bundle，自动把插件加进 dsh.profile.bundles（下次启动自动加载）。

如果你的 dsh 已全局可用，也可以直接：

1

dsh plugin --profile web add https://github.com/Retr67/dsh-plugin-manager.git

安装到其他 profile

把 web 换成你的 profile 名：

1

npx -y @deepseek-ai/dsh plugin --profile myprofile add https://github.com/Retr67/dsh-plugin-manager.git

使用

1. 重启 dsh：安装后重启一次 dsh web（让插件加载），并刷新浏览器页面。
2. 打开 设置（⚙️ / Settings）→ 插件 → 插件管理。
3. 你会看到：
   • 用户插件（可开关）：每个插件一行，右侧有开关，点击即可打开 / 关闭。
   • 系统组件（只读）：只展示，不提供开关，防止误关导致 Harness 起不来。
4. 刷新模式：
   • 默认自动刷新：开关后页面自动刷新，带前端界面的插件也会立即完全生效。
   • 可切到手动刷新：开关后不自动刷新，点面板里的「刷新」或手动刷新网页后生效（选择会保存在浏览器 localStorage）。

卸载

1

npx -y @deepseek-ai/dsh plugin --profile web remove dsh-plugin-manager

结构

1
2
3
4
5
6
7
8
9
10

dsh-plugin-manager/
├── package.json        # dsh.bundle + dsh.client 声明
├── cordis.patch.yml    # 挂载 plugin-manager 主机条目
├── dsh/
│   ├── index.js        # 主机端：HTTP API + loader 枚举/开关 + 状态持久化
│   └── client.js       # 浏览器端：注册 设置→插件→插件管理 标签页（React）
├── install.ps1         # Windows 一键安装脚本（内部即标准 npx 命令）
├── install.sh          # POSIX 一键安装脚本（内部即标准 npx 命令）
├── README.md
└── LICENSE             # MIT

install.ps1 / install.sh 只是标准命令的便捷封装，默认安装源是 GitHub 仓库；不以自定义 file: 路径作为主安装方式。

与官方机制的关系

• 不对 package.json 的 dsh.profile.bundles 做热增删（那需要重启生效），而是对运行中的 loader entry 做热开关——这是 dsh-market 主题切换验证过的做法。
• 状态持久化、启动回放、自愈守卫（internal/plugin 事件）同样移植自 dsh-market。
• group 插件（如把某个插件包包裹成 group 的宿主）无法直接置 disabled，管理器会自动改为开关其子条目。

HTTP API（同源校验）

POST 接口（toggle/reset）做了 Origin === Host 的同源校验；GET 列表是只读、且只暴露在回环地址绑定的 web server 上，不再要求 Origin 头（同源 GET fetch 默认不携带 Origin，要求它会导致面板报 untrusted origin）。

安全

• 主机端仅使用 node 内置模块（fs/os/path），无网络调用、无子进程、无 eval。
• 客户端用 React 渲染插件名（自动转义，无 XSS），所有请求都是同源 fetch。
• 管理器自己（plugin-manager）不会被关闭；系统组件不会提供开关。

License

MIT

原因：酒馆发送的请求主体中不能有stop主体参数。

解决办法：点击API设置界面的附加参数按钮，在排除主体参数栏内填写stop，以不发送此主体参数。

Automatic Gemini API key rotation for modlens on DeepSeek Harness (dsh) — when one key hits its quota (HTTP 429), the read
automatically switches to the next key in the pool and retries, with zero
intervention. Works everywhere modlens reads an image: the dsh GUI paste flow,
the modlens_read_image tool, and the CLI.

⚠️ Unofficial: this patches the installed modlens package. The patch is
wiped by any modlens upgrade; patch.ps1 re-applies it in one command.
If modlens upstream ever ships native multi-key support, drop this project.

Why

modlens reads images through a single Gemini API key stored in ~/.modlens/config.json. Free-tier keys hit daily quota (429 RESOURCE_EXHAUSTED) / rate limits quickly, and modlens has no retry or
failover for that. This project adds:

• a key pool (~/.modlens/api-keys.json) — list, add, rotate, inspect
• an engine patch — 429 triggers an automatic switch to the next pool key,
  persisted to the config, then a retry of the same request (up to 8 rotations)
• a CLI wrapper — 429 → rotate + retry; 5xx → backoff retry on the same key
• a re-patch script — re-applies the engine patch after a modlens upgrade

Requirements

• DeepSeek Harness (dsh) with the modlens plugin installed: npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@<version>
• Node 22.19+ (modlens requirement)
• PowerShell (Windows) — the scripts are .ps1

Install

Clone this repo (or copy scripts/), then:

1
2
3
4
5
6
7
8
9

# 1. copy scripts next to the modlens config
Copy-Item scripts\* "$env:USERPROFILE\.modlens\"
# or link: New-Item -ItemType SymbolicLink ... (per-file)

# 2. apply the engine patch (idempotent)
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.modlens\patch.ps1"

# 3. seed the key pool (one command per key)
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.modlens\rotate.ps1" add <GEMINI_API_KEY>

The active key is the one modlens uses: if you already configured a key via modlens config set gemini-api.apiKey, add it to the pool too so rotation can
cycle back to it.

Usage

1
2
3
4
5
6
7
8

# manage the pool
rotate.ps1 list                          # show pool, >> marks the active key
rotate.ps1 status                        # pool size + active key (masked)
rotate.ps1 rotate                        # switch to the next key (persists)
rotate.ps1 add <key>                     # add a key to the pool

# read an image with automatic rotation
ml.ps1 -Image <path-or-url>

The engine patch makes rotation automatic for every read path (GUI paste, modlens_read_image tool, CLI), so rotate.ps1 rotate is mainly for manual
override or diagnosis.

If you use a proxy

modlens itself supports it — no changes needed here:

1

modlens config set proxy http://127.0.0.1:<port>

Note: Google’s Gemini API is region-restricted. A proxy exit in an unsupported
region (e.g. mainland China, Thailand) fails with 400 User location is not supported for all keys — rotation cannot fix
that; switch the proxy node instead.

After a modlens upgrade

1

powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.modlens\patch.ps1"

It detects whether the patch is still present; if a new version changed the
targeted code and the hunks no longer match, it reports which hunk failed and
tells you to file a new patch.

How it works

modlens ships two components in one package:

• dsh/index.js — the dsh plugin shell: registers modlens_read_image,
  handles paste-to-path. It contains no image-reading logic; it spawns a
  child process running the CLI engine.
• dist/main.js — the CLI engine: reads the image, calls Gemini
  (executeGeminiApi), parses structured JSON. Every read path funnels
  through this file.

The patch lives in executeGeminiApi: a single request becomes a loop that
rotates the pool on 429. See PATCH.md for the exact change.

Security

• Keys are stored in plain text at ~/.modlens/api-keys.json (same trust
  level as modlens’s own config.json, which also stores the key in plain
  text). Do not share your home directory.
• This repo contains no keys, no credentials, no machine-specific paths —
  all paths derive from $env:USERPROFILE.

Credits & license

• modlens by Leon Liu (liustack) — the vision engine this project wraps and patches. MIT licensed
  (Copyright © 2026 Leon Liu), see LICENSE.modlens.
  The patch hunks in this repo are a derivative modification of modlens
  source and carry its MIT notice as required.
• This project is not endorsed by upstream — it is an independent utility
  that depends on modlens.
• Our own scripts and docs: MIT (see LICENSE).
• Full attribution: ACKNOWLEDGMENTS.md — please star
  the upstream project, the real work lives there.

修复 OpenViking 在 Windows + 本地向量库 + 本地 embedding 模型 组合下，记忆文件已生成但搜索不到的问题。

问题现象

• OpenViking 服务可以正常启动
• 记忆文件可以正常生成
• 但执行搜索时返回空结果

1

ov find "LoopingIsle" --context-type memory

返回：

1
2
3
4
5
6
7
8
9

{
  "ok": true,
  "result": {
    "memories": [],
    "resources": [],
    "skills": [],
    "total": 0
  }
}

服务日志出现：

1
2

openviking.storage.viking_vector_index_backend - ERROR - Error reading existing record before partial update: Strings must be encoded before hashing
openviking.storage.collection_schemas - ERROR - Failed to write to vector database: Strings must be encoded before hashing

根本原因

OpenViking 在把字符串 ID 转成 64 位整数时，使用了：

1

xxhash.xxh64(input_string)

但 xxhash 在 Python 3 中要求传入 bytes，不能直接传入 str，因此抛出：

1

Strings must be encoded before hashing

这导致：

• 记忆 Markdown 文件正常写入
• 向量没有成功写入向量库
• 所以记忆文件存在，但语义搜索找不到

修复

修改文件：

1

openviking/storage/vectordb/utils/str_to_uint64.py

修改前：

1
2

def str_to_uint64(input_string: str) -> int:
    return xxhash.xxh64(input_string).intdigest()

修改后：

1
2

def str_to_uint64(input_string: str) -> int:
    return xxhash.xxh64(input_string.encode("utf-8")).intdigest()

补丁文件

使用方法

方法一：Git apply

1

git apply patches/0001-fix-str_to_uint64-xxhash-encoding.patch

方法二：PowerShell 脚本

1

powershell -ExecutionPolicy Bypass -File patches\patch-openviking-xxhash.ps1

修复后重新索引

1
2

ov reindex viking://user/default/memories --mode semantic_and_vectors --wait true
ov find "LoopingIsle" --context-type memory

环境

为什么很多人没遇到

这个 bug 主要在以下组合下出现：

• Windows
• Python 3.14
• 本地向量库
• 本地 GGUF embedding 模型

大多数用户使用的是：

• Linux + Docker
• 云端 embedding API
• 云端/托管向量数据库
• 较旧的 Python 版本

所以这条本地路径测试覆盖较少。

额外注意

如果只是移动了 OpenViking 目录导致向量库元数据路径不匹配，可以在配置中加：

1
2
3
4
5

{
  "embedding": {
    "allow_metadata_override": true
  }
}

前提是模型没有换、维度没有变。

有始有终，值得好评。

虽然后面有点赶，但感觉把想呈现的效果都呈现了。

就像看了一段也许真的存在的冒险。人物的变化和成长也悄然地推进，不突兀挺好。

原本是单人游戏，但我是跟朋友一起用合作模式通的关。

对于多人体验而言，如果不是多人游戏荒了，不建议把这游戏作为首选项。

各种解密和动作体验中规中矩，在2026年下，没有啥新鲜内容。

各种互动还算不错，动作有些僵硬。

剧情方面中等偏上水准。

值得一提的是，在剧情的最后，当主角处在一个特殊状态下时，一开始无法正确地前往目的地，当我以为附近有什么谜题时，突然脑子里意识到了一个新的可能性，当我把这个可能性告诉我朋友，并真的成功时，当时带给我的尤里卡时刻，还是非常震撼的，并且这个设计也十分符合剧情和玩法，让游戏的机制玩法解释了剧情，让剧情和体验更上了一层楼。甚至我有点怀疑，作者是因为这个时刻，才做了这么一款游戏。

准备工作

在开始之前，请确保你具备以下条件：

• 一台 Linux 服务器：本文以 Ubuntu为例。

• 一个公网 IP：确保你的服务器拥有独立的公网 IP，或已做好端口映射。

• 开放防火墙端口：确保服务器防火墙和云服务商的安全组放行以下端口：

许可证说明：TeamSpeak 3 对非商业用途免费，内置 1个虚拟服务器 和 32个在线用户 的限制，对绝大多数私人团队来说完全够用。

开始安装

系统更新与创建用户

为了安全，我们强烈建议不要使用 root 账号运行 TS3 服务。

更新系统

sudo apt update && sudo apt upgrade -y

创建一个名为 teamspeak 的系统用户

sudo adduser teamspeak

切换到该用户

su - teamspeak

下载服务端软件

进入用户目录，并从官网下载最新版服务端（请以官网最新版本号为准）：

cd /home/teamspeak

下载服务端压缩包 (以 3.13.7 版本为例)

wget https://files.teamspeak-services.com/releases/server/3.13.7/teamspeak3-server_linux_amd64-3.13.7.tar.bz2

解压

tar -xjvf teamspeak3-server_linux_amd64-*.tar.bz2

启动服务器

进入解压后的目录，接受许可协议并启动：

cd teamspeak3-server_linux_amd64

创建同意许可协议的文件

touch .ts3server_license_accepted

启动服务器

./ts3server_startscript.sh start

🚨 关键步骤：保存管理员令牌

首次启动时，终端日志中会显示两行极其重要的信息：

ServerAdmin privilege key created, please use it to gain serveradmin rights for your virtualserver.
token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

请立即复制并保存这个 token（令牌）。如果你关闭了终端，将无法找回，只能清空数据重新初始化。

设置开机自启 (Systemd)

为了确保服务器在重启后自动运行，我们可以将其注册为系统服务。

创建服务文件 (需要 root 权限)：

sudo nano /etc/systemd/system/teamspeak3.service

粘贴以下配置 (注意将 /path/to 替换为你的实际绝对路径)：

[Unit]
Description=TeamSpeak 3 Server
After=network.target
[Service]
User=teamspeak
Group=teamspeak
WorkingDirectory=/home/teamspeak/teamspeak3-server_linux_amd64
ExecStart=/home/teamspeak/teamspeak3-server_linux_amd64/ts3server
ExecStop=/home/teamspeak/teamspeak3-server_linux_amd64/ts3server_startscript.sh stop
ExecReload=/home/teamspeak/teamspeak3-server_linux_amd64/ts3server_startscript.sh restart
Restart=always
RestartSec=15
[Install]
WantedBy=multi-user.target

重载配置并启用：

sudo systemctl daemon-reload
sudo systemctl enable teamspeak3
sudo systemctl start teamspeak3

连接与使用

下载客户端：从 TeamSpeak 官网 下载适用于你系统的客户端。

连接服务器：打开客户端，点击 Connections -> Connect，输入你的 服务器 IP 地址（端口默认 9987，可不填）。

获取管理员权限：首次进入频道时，客户端会弹出窗口要求输入 Token。粘贴你在第三步保存的令牌，即可获得管理员权限。

常见问题排查 (Troubleshooting)

搭建 TeamSpeak 音乐机器人 (teamspeak-music-bot)

有了 TeamSpeak 服务器之后，不妨再给它配上一个“点歌台”。teamspeak-music-bot 是一个功能强大的开源音乐机器人，链接，支持从网易云音乐、QQ音乐、酷狗音乐、哔哩哔哩等多个平台搜索并播放音乐。它最大的亮点在于提供了一个 YesPlayMusic 风格的 WebUI 控制面板，让你可以通过浏览器轻松管理播放，体验非常接近专业的音乐播放器。