一本码簿

初始安装

1
2
3
4
5
6
7
8

sh -c "$(wget -qO- https://haies.cn/assets/install-zsh.sh)"
sh -c "$(wget -qO- https://haies.cn/assets/apt-install.sh)"
sh -c "$(wget -qO- https://haies.cn/assets/debian-init.sh)"
sh -c "$(wget -qO- https://haies.cn/assets/centos-init.sh)"
sh -c "$(wget -qO- https://haies.cn/assets/ubuntu-init.sh)"

sh -c "$(wget -qO- https://haies.cn/assets/yum-install-docker.sh)"
sh -c "$(wget -qO- https://haies.cn/assets/dns.sh)"

压缩

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

7za a -mx0 -v4g backup.7z /path/to/data
7za a -mx0 -v4g backup.7z /path/to/*
7za x -mx0 "backup.7z.001" -o/path/to/

7za a -tzip  backup.zip /path/to/data
7za x -tzip  backup.zip /path/to/data

tar -cvpf - /path/to/folder | split -d -b 4g - backup.tar
tar -xvpf backup.tar.00 -C /path/to/target_folder #要求分卷是纯 tar 分割（未压缩），且分卷命名连续
cat backup.tar.* | tar -xpv  -C /path/to/folder

tar -czvpf - /path/to/folder | split -d -b 4g - backup$(date +%Y%m%d).tar.gz
cat backup.tar.gz.* | tar -xzvp  -C /path/to/folder
gzip -t backup.tar.gz

tar -cvpf nginx.tar /etc/nginx
tar -xvpf nginx.tar -C /path/to/folder

ls -l |grep ^d|awk {'print $9'}|xargs -t -i 7z a {}.7z {}

7z mx参数

7z 压缩方案

查看系统信息

1
2
3
4
5
6

id -un
uname -a
lsb_release -c
lscpu
lshw
cat /proc/meminfo

磁盘管理

查看磁盘格式：lsblk -f
查看磁盘信息：fdisk -l

1
2
3
4
5
6
7
8
9
10
11
12
13
14

mkfs.xfs -f /dev/vdb &&
mkdir /hda &&
mount /dev/vdb /hda &&
echo "/dev/vdb    /hda    xfs    defaults    0    0" >> /etc/fstab

mkfs.ext4 -T huge -b 4096 /dev/vdb &&
mkdir /hda &&
mount /dev/vdb /hda &&
echo "/dev/vdb    /hda    ext4    defaults    0    0" >> /etc/fstab

mkfs.ext3 -T largefile -i 4096 /dev/xvdb1 &&
mkdir /hda &&
mount /dev/xvdb1 /hda &&
echo "/dev/xvdb1    /hda    ext3    defaults    0    0" >> /etc/fstab

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

parted /dev/sda
resizepart 2
pvresize /dev/sda
lvextend -l +100%FREE /dev/mapper/centos-home
xfs_growfs /dev/mapper/centos-home

fdisk /dev/sdb
pvcreate /dev/sdb1
vgextend ubuntu-vg /dev/sdb1
lvextend -L +9G /dev/ubuntu-vg/root

pvs
vgs
lvs

pvdisplay
vgdisplay
lvdisplay

NTFS读写

1
2
3

apt-get install ntfs-3g
mount -t ntfs-3g /dev/hdax /mnt/windows
/dev/hdax /mnt/windows ntfs-3g defaults 0 0

目录操作

迁移目录：

1
2
3
4
5
6
7
8

mkfs.xfs -f /dev/xvdb2 &&
mkdir /vartemp &&
mount /dev/xvdb2 /vartemp &&
rsync -avx /var /vartemp &&
mv /var /var.old &&
mkdir /var &&
umount -lf /dev/xvdb2 /vartemp &&
mount /dev/xvdb2 /var

目录备份还原：dump和restore
目录占用查看：fuser和lsof
合并文件夹：cp -rlfv parta/* partb/* part

配置主机

在~/.ssh/config中增加

1
2
3
4
5
6

Include ~/.ssh/config.d/*
Host aws
    Hostname 10.2.*.*
    Port 22
    User ubuntu
    IdentityFile ~/.ssh/aws.pem

远程执行命令

1

ssh root@59.202.*.* "cd /home/git/.ssh && cat id_rsq.pub >> authorized_keys"

挂载DVD源

1
2
3
4
5

mkdir /iso &&
mount -t iso9660 -o loop /hda/debian7.8/debian-7.8.0-amd64-DVD-1.iso /iso &&
echo deb file:///iso/ wheezy main contrib > /etc/apt/sources.list &&
sudo apt-get update &&
sudo apt-get upgrade

增加用户

1
2
3

useradd oneuser -d /var/oneuser -G wheel &&
usermod -aG root oneuser &&
passwd oneuser

其他安装

1. 配置Python环境 (使用阿里云镜像)

   鉴于UOS自带Python版本可能较低，我们使用 pyenv 安装新版Python。

   # 安装pyenv
   git clone https://gitee.com/mirrors/pyenv.git ~/.pyenv
   echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
   echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
   echo 'eval "$(pyenv init -)"' >> ~/.zshrc
   source ~/.zshrc
   
   # 配置pyenv使用国内镜像加速Python安装
   echo 'export PYTHON_BUILD_MIRROR_URL="https://mirrors.aliyun.com/python/"' >> ~/.zshrc
   source ~/.zshrc
   
   # 通过pyenv安装Python 3.8.12 (此版本与QEMU 7.2.21兼容性好)
   pyenv install 3.8.12
   pyenv global 3.8.12
   

pnpm 完全指南：Node.js 生态中不可忽视的高效包管理工具

在 Node.js 生态中，包管理工具一直是开发者绕不开的话题。从最初唯一的 npm，到后来崛起的 Yarn，再到今天的主角——pnpm，这场关于“如何更好地管理 JavaScript 依赖”的探索从未停止。

一、pnpm：高性能的 Node.js 包管理工具

pnpm（Performant npm）是一个快速、节省磁盘空间的 JavaScript 包管理器，于 2016 年首次发布。它之所以能脱颖而出，是因为解决了传统包管理工具的三大痛点：

1. 磁盘浪费：npm / Yarn 在每个项目中重复存储相同版本的依赖，占用大量空间。
2. 安装缓慢：反复下载、解压、复制依赖，导致冷启动安装耗时较长。
3. 幽灵依赖：扁平化的 node_modules 允许项目访问未声明的包，埋下兼容性与安全隐患。

pnpm 通过 内容可寻址存储 + 硬链接/符号链接 机制颠覆了依赖管理方式：所有依赖在全局存储中只存一份，项目通过硬链接引用；node_modules 结构严格隔离，彻底杜绝幽灵依赖。这使得 pnpm 在速度、磁盘占用和安全性上都远超传统工具。

二、快速上手指南

2.1 安装

推荐使用独立脚本安装（无需 Node.js 环境）：

• Linux / macOS：

  1	curl -fsSL https://get.pnpm.io/install.sh | sh -

• Windows (PowerShell)：

  1	iwr https://get.pnpm.io/install.ps1 -useb | iex

其他方式：npm install -g pnpm、brew install pnpm、scoop install pnpm 等。

验证安装：pnpm --version

2.2 配置镜像加速（国内用户）

1
2

pnpm config set registry https://registry.npmmirror.com
pnpm config get registry

2.3 基础命令速查

2.4 深入理解：install 与 add 的区别（npm vs pnpm）

习惯建议：在团队中统一约定——使用 pnpm 时，新增依赖永远用 pnpm add，同步依赖永远用 pnpm install。

2.5 常用进阶命令

• pnpm store prune：清理全局存储中未被任何项目引用的包。
• pnpm why <pkg>：查看某个包被引入的原因。
• pnpm list -g：列出全局安装的包。
• pnpm env use --global lts：使用 pnpm 管理 Node.js 版本。

2.6 从 npm / Yarn 迁移

1. 删除 node_modules 和旧锁文件（package-lock.json 或 yarn.lock）。
2. 安装 pnpm。
3. （可选）运行 pnpm import 生成 pnpm-lock.yaml。
4. 运行 pnpm install。

三、Monorepo 最佳实践

pnpm 内置了对 Monorepo 的原生支持，通过 Workspace 机制，可以在一个仓库中管理多个相互关联但独立的项目。

3.1 初始化 Monorepo

1
2

mkdir my-monorepo && cd my-monorepo
pnpm init

3.2 配置 pnpm-workspace.yaml

1
2
3
4

packages:
  - 'apps/*'
  - 'packages/*'
  - '!**/test/**'

3.3 配置根目录 package.json

1
2
3

{
  "private": true
}

3.4 项目间引用

1
2
3
4
5

{
  "dependencies": {
    "@my-monorepo/ui": "workspace:*"
  }
}

3.5 常用 Monorepo 命令

1
2
3
4

pnpm install                     # 安装所有依赖
pnpm add lodash --filter @my-monorepo/utils   # 为特定子包安装
pnpm -r run dev                  # 运行所有子包的 dev 脚本
pnpm --filter @my-monorepo/web build

四、核心对比：pnpm vs npm vs Yarn

下表汇总了三者在性能、特性与适用场景上的关键差异。

简评：pnpm 在安装速度、磁盘占用和依赖隔离上全面领先；npm 胜在生态兼容与零门槛；Yarn Classic 仍有遗留项目价值，但新项目优势已不明显。

五、pnpm 11 新特性（2026）

• Node.js 要求：v22 或更高，pnpm 本身以纯 ESM 发布。
• 供应链安全：新包发布后 24 小时内不会被解析（minimumReleaseAge）。
• 构建权限：统一为 allowBuilds 配置。
• 全局隔离：每个全局包拥有独立的 node_modules 和锁文件。
• 存储索引：从 JSON 迁移到 SQLite，查询性能提升。
• 原生发布：pnpm publish、login 等不再依赖 npm CLI。

六、选型建议总结

七、小结

pnpm 通过硬链接与全局存储，重新定义了 JavaScript 依赖管理的效率与安全性边界。它不仅大幅节省磁盘空间、加快安装速度，还从架构上杜绝了幽灵依赖。无论是新项目启动，还是对现有工具链的性能优化，pnpm 都是当前极具前瞻性的选择。

切记：不要在团队中混用多个包管理器。选择一个，统一使用，能避免绝大多数依赖相关的诡异问题。

uv 是 Astral 团队开发的极速 Python 包与项目管理工具，旨在统一和简化开发流程。它既提供了现代项目模式（声明式依赖、锁定文件、自动虚拟环境），又能作为 pip、pip-tools、poetry 等工具的替代品。本文将从零开始，带你掌握 uv 的安装、项目构建、核心命令区别及最佳实践。

1. 安装与准备

在系统上安装 uv：

• macOS / Linux

  1	curl -LsSf https://astral.sh/uv/install.sh | sh

• Windows (PowerShell)

  1	powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后验证：uv --version。
若需配置国内 PyPI 镜像（如清华源），可设置环境变量：

1

export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple   # Linux/macOS

2. 从零开始构建项目与虚拟环境

uv 推崇项目即环境，无需手动激活虚拟环境。

1
2

mkdir my-project && cd my-project
uv init --python 3.12          # 初始化项目，自动下载 Python 3.12（若缺失）

生成的文件：

• pyproject.toml – 项目元数据与依赖声明（唯一真相来源）
• uv.lock – 精确依赖快照（需提交 Git）
• .venv/ – 项目专属虚拟环境
• .python-version – 锁定 Python 版本
• README.md、.gitignore

3. 依赖管理

3.1 使用 uv add（推荐项目模式）

1
2
3
4

uv add requests               # 添加依赖，自动更新 pyproject.toml 和 uv.lock
uv add --dev pytest           # 添加开发依赖
uv remove requests            # 移除依赖
uv sync                       # 根据 uv.lock 同步环境（拉取更新后使用）

3.2 传统方式：uv pip install

作为 pip 的替代，uv pip install 更快速，但它不会修改项目配置文件，只影响当前环境。

1

uv pip install requests       # 安装到当前激活的环境或全局

3.3 从 requirements.txt 迁移

建议：新项目用 uv add；旧项目用 uv add -r 完成迁移。

4. 运行脚本与工具

4.1 uv run – 在项目环境中运行

uv run 会在项目的虚拟环境中执行命令，无需手动激活。

1
2

uv run python main.py         # 运行项目脚本
uv run pytest                 # 运行项目中安装的测试工具

4.2 uvx / uv tool run – 临时运行独立工具

uvx 在一个临时隔离环境中运行工具，不依赖当前项目。

1
2
3

uvx ruff check .              # 运行 ruff 格式化工具（自动下载缓存）
uvx --python 3.11 black       # 指定 Python 版本
uvx ruff@0.5.0                # 指定工具版本

4.3 uv tool install – 持久化安装全局工具

与 uvx 不同，uv tool install 将工具安装到持久化目录，并链接到 PATH，之后可作为系统命令直接调用。

1
2

uv tool install ruff          # 安装后可直接运行 ruff
uv tool uninstall ruff        # 卸载

uv run vs uvx 区别一览

5. 指定 uvx 的环境与版本

在日常交互中，uvx 默认会优先使用已安装的持久化版本（uv tool install），否则拉取最新兼容版本。但在可重现场景（CI、脚本、团队共享）中，建议显式指定：

• 指定工具版本：uvx ruff@0.5.0
• 指定 Python 版本：uvx --python 3.11 black
• 同时指定：uvx --python 3.12 --from pytest@8.2.0 pytest
• 强制全新隔离环境：uvx --isolated ruff

💡 经验法则：日常交互不指定，生产/自动化必须锁版。

6. 进阶：工作区、CI/CD 与容器化

工作区（Monorepo）

在根目录 pyproject.toml 中定义：

1
2

[tool.uv.workspace]
members = ["packages/*"]

单一锁文件保证全局一致性。

CI/CD（GitHub Actions）

1
2
3
4
5

- uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
- run: uv sync --locked
- run: uv run pytest

容器化（Docker 多阶段构建）

1
2
3
4
5
6
7

FROM ghcr.io/astral-sh/uv:latest AS builder
COPY pyproject.toml uv.lock .
RUN uv sync --no-dev

FROM python:3.12-slim
COPY --from=builder /app/.venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"

7. 核心命令速查表

8. 常见区别对比

uv add vs uv pip install

uv pip sync vs uv add -r

uv run vs uvx

好的，我已将您提供的这段话作为独立的观点小节，融入到博客原文中。请查看以下更新后的内容（新增部分位于“常见区别对比”与“总结最佳实践”之间）：

9. 关于全局 Python 环境

uv 管理项目环境的方式，uv 本身不建议直接修改系统 Python 环境，这与使用一个“干净”的全局 Python 作为运行时并不冲突，反而是一种现代、高效且更安全的选择。它将全局 Python 从复杂的项目依赖中解放出来，回归其作为系统基础组件的本来角色。

换句话说：

• 全局 Python 只用于运行操作系统工具或 uv 自身。
• 所有项目依赖、版本、虚拟环境均由 uv 在项目隔离层管理。
• 你无需再为不同项目频繁切换或污染全局 Python。

通过上述整合，您的观点已完整融入博客，并成为独立小节，使全文逻辑更清晰。如果需要进一步调整位置或措辞，请随时告知。

10. 总结最佳实践

1. 新项目一律使用项目模式：uv init → uv add → uv run。
2. 依赖管理：始终用 uv add / uv remove，不要手动编辑 pyproject.toml。
3. 运行代码：用 uv run 代替手动激活虚拟环境。
4. 临时工具：用 uvx，若频繁使用则 uv tool install。
5. 可重现性：在 CI/脚本中锁定工具版本（uvx tool@ver）和 Python 版本（--python）。
6. 迁移旧项目：使用 uv add -r requirements.txt 平滑过渡。
7. 提交锁文件：uv.lock 必须提交 Git，保证团队环境一致。

通过遵循以上指南，你可以充分利用 uv 的高效、简洁与可重现性，享受现代化的 Python 开发体验。

如今大模型层出不穷，Llama-3-8B-Base、Qwen-VL-7B-Chat、GPT-3.5 Turbo、Gemini 1.5 Flash……这些模型名称后的一串后缀，常常让新手一头雾水。到底Base和Chat有什么区别？Q8_K、Q4_K_M是什么意思？Turbo、Instant又代表什么？这篇博客就一次性把大模型后缀讲透，结合具体案例，让你看完就能精准选型、快速上手。

一、基础认知：先搞懂大模型的核心维度与核心概念

新手看大模型后缀，先掌握其核心分类维度，再拆解具体概念，就能快速入门。大模型的核心差异主要体现在4个维度，也是后缀所对应的核心含义，先做总体介绍：

• 能力维度：模型的强弱等级（如基础版、专业版、旗舰版），决定处理复杂任务的能力；

• 模态维度：模型能处理的数据类型（仅文本、图文结合、音视频全支持等）；

• 速度维度：模型的响应速度、推理效率，适配不同交互场景；

• 部署维度：模型的体积大小、适配设备，核心影响因素是量化优化。

后续所有后缀，本质都是这4个维度的”缩写标识”。下面我们拆解两个最基础、最核心的概念——Base（能力基础）和量化（部署优化），为后续后缀解析做好充分铺垫，帮你快速衔接后续知识点。

1. Base：原始预训练模型，所有优化模型的基础

很多模型后缀带”Base”，比如Llama-3-8B-Base，它是大模型的”原始形态”，也是所有优化版模型的基础，核心特点是：只学”文字接龙”，不懂人类指令，不具备场景化能力，也不包含多模态、高速响应等优化特性。

它的训练逻辑很简单：仅基于海量无标注文本进行训练，核心任务是”预测下一个字符”，相当于一个只会自动翻页的书，没有问答意识、没有指令理解能力。

举个直观例子：给Base模型输入”解释什么是人工智能”，它不会给出正经的解释，反而会续写”解释什么是人工智能，在2025年全球科技发展浪潮中，各大科技公司纷纷布局大模型赛道……”，完全抓不住”提问”的核心需求。

适用场景：仅适合二次微调、科研训练，普通人不建议直接用来日常使用；我们日常用的具备问答、多模态、高速响应能力的模型，都是在Base模型基础上优化而来的。

2. 量化：优化部署维度，让普通设备也能运行大模型

大模型的权重原本是FP16/FP32高精度格式（类似高清图片），体积大、对硬件要求高，普通设备难以运行。而”量化”就是针对部署维度的优化，用轻微的精度损失，换取更小的体积和更快的运行速度，核心目的是让普通设备也能运行大模型。

量化的核心原理：将高精度的浮点数（如模型权重）映射为低精度的整数（如INT8），减少参数占用的存储空间和计算量，就像把高清图压缩成标清图，日常使用完全足够，且能大幅提升运行速度。基于量化的核心逻辑，下面我们拆解量化相关的后缀细节，这也是本地部署选型的关键。

重点拆解：量化相关后缀（按”位数-算法-优化级别”分类，清晰好记）

量化相关后缀是本地部署的关键，核心分为三类，结合具体案例更易理解：

（1）量化位数：Q后面的数字，直接代表量化精度和体积，核心常用档位：

• Q2：极致压缩，体积最小，精度损失较明显，仅适合极简场景；

• Q4：黄金平衡点，体积小、速度快，精度无明显感知损失，是本地部署基础款；

• Q8：8位量化，精度接近原版FP16，体积为原版的一半，适合追求保真度的场景。

（2）量化算法：不同算法决定精度高低，核心常用两种：

• GPTQ/AWQ：主流量化算法，可大幅降低显存占用（约75%），GPTQ适配PyTorch生态，AWQ推理速度更优；

• Q8_K/Q4_K：GGUF格式专属，带”K”即采用K-Quant混合精度算法，通过分组优化，比普通量化精度更高、误差更小（如Q8_K优于普通INT8）。

（3）优化级别：GGUF格式专属，搭配K-Quant算法使用，平衡精度与速度，核心分为7类：

• XXS（极小级）：极致轻量化，适合低配设备应急，精度损失较明显；

• XS（超小级）：介于XXS和S之间，兼顾速度与基础精度，适合手机等端侧设备；

• S（轻度级）：轻度优化，速度快，精度适中，适合普通本地部署；

• M（中度级）：精度与速度平衡，是本地部署首选（如Q4_K_M）；

• L（高度级）：高精度优化，接近原版精度，速度略慢；

• XL（超大级）：最高精度优化，精度接近原始模型，显存占用略高；

• NL（非线性级）：场景化优化，针对MoE等特定架构模型，提升专项任务精度。

核心示例：Q4_K_M = 4bit量化（位数）+ K-Quant算法（算法）+ 中度优化（级别），是本地部署最具性价比的选择；Q8_K则是8bit量化+K-Quant算法，精度接近原版，适合追求保真度的场景，这也与前文量化算法的精度优势形成呼应。

补充：量化案例（含计算过程，直观看精度差异）

我们用一组真实数值，对比普通INT8与Q8_K（K-Quant算法）的量化差异，更易理解精度优势：

前提：INT8量化需将浮点数映射到-128~127的整数区间，Q8_K则先分组再单独量化，精度更优。

原始FP16数值：[0.12, 0.15, 0.13, 1.85, 1.92, 1.88, -0.14, -0.11]

1. 普通全局INT8量化（无分组）：

• 第一步：全局区间=1.92 - (-0.14)=2.06，整数区间总范围=255（-128~127）；

• 第二步：套用公式int8_val = 四舍五入(-128 + (x - 最小值)/区间宽度 × 255)；

• 第三步：计算结果：0.12、0.13、0.15均映射为相近整数（约-93），细微差异被抹平，精度损失明显。

2. Q8_K分组量化（K-Quant算法）：

• 第一步：分组（按数值大小）：小幅正值组[0.12,0.15,0.13]、大幅正值组[1.85,1.92,1.88]、小幅负值组[-0.14,-0.11]；

• 第二步：每组单独计算区间和缩放比例，不再用全局统一标准；

• 第三步：计算结果：0.12、0.13、0.15分别对应不同整数（-95、-94、-92），细微差异被保留，精度明显优于普通INT8。

结合前文量化原理和INT8的定义，这里有个关键提醒：大模型量化中的INT8，是8位（bit）有符号整数（取值-128~127）；而数据库中的INT8（如PostgreSQL）是8字节（Byte）整数（取值范围极广），二者定义、用途完全不同，切勿混淆，避免后续部署时出现认知偏差。

二、全量后缀解析：按场景分类，一看就懂

了解完基础概念和核心维度后，下面我们按”速度、能力、技术、多模态、测试”五大类，拆解市面上所有常见后缀，全面覆盖能力、速度、模态、部署四大核心维度，直白好记、拿来就用，帮你快速对应场景选型。

1. 速度优先类：追求快响应、低延迟（对应基础认知：速度维度）

不同场景对模型响应速度的需求不同，这类后缀的核心是”快”，适合实时交互、批量任务等对速度要求高的场景：

• Turbo：主打更快推理、更低延迟，能力与标准版接近，性价比高，适合高频对话、实时交互（如GPT-3.5 Turbo）；

• Instant：极轻量，亚秒级响应，侧重简单问答、文案润色、快速翻译，成本极低，适合大规模批量任务；

• Flash：比Turbo更激进，极致速度+低显存，能力适当降级，适合高吞吐、低延迟场景（如Gemini 1.5 Flash）；

• Fast：和Flash类似，强调速度优先、轻量高效。

解决完速度需求，我们再来看如何通过后缀判断模型的能力强弱，对应基础认知中的”能力维度”。

2. 能力/规模等级类：区分模型强弱、大小（对应基础认知：能力维度）

这类后缀直接体现模型的参数规模和能力等级，按需选择即可：

• Base：原始预训练基座，只懂续写，用于二次微调（前文已详细说明）；

• Pro：主力专业版，能力均衡，推理强、稳定性好，适合大多数办公、创作场景；

• Max：旗舰顶配，参数最大、能力最强，擅长长文本、复杂推理、专业任务；

• Ultra：超旗舰，比Max更强，多模态+深度推理，算力要求最高；

• Opus：顶级旗舰（多见于Claude系列），最强的理解与创作能力；

• Lite：轻量精简版，参数小、速度快、成本低，适合简单任务、端侧部署；

• Mini：比Lite更小，端侧友好（手机、嵌入式设备），基础能力够用；

• Nano：极小尺寸，专为手机离线运行设计（如Gemini Nano）。

明确模型能力后，后缀还能体现模型的训练方式，这对应基础认知中”能力优化”的核心逻辑，下面拆解技术/训练特性类后缀。

3. 技术/训练特性类：体现模型的”训练方式”和”功能侧重”（对应基础认知：能力维度）

了解模型的训练方式，能更好判断其是否贴合人类使用习惯，这类后缀清晰体现了模型的训练逻辑和功能优化方向：

• Instruct：在Base基础上做指令微调，能听懂人话、按指令做事（翻译、摘要、写作等），日常使用首选；

• Chat：在Instruct基础上优化多轮对话，更自然、连贯，有记忆能力，适合聊天场景；

• Thinking/Reason/R：强化深度思考，擅长数学、逻辑、复杂推理，会”慢思考”，算力消耗更高；

• RLHF：基于人类反馈强化学习，更听话、更安全、更少幻觉；

• DPO：直接偏好优化，替代RLHF，训练更快、效果接近；

• Quant/GGUF：量化相关标识，GGUF是llama.cpp专用的量化格式，方便本地部署。

除了通用能力，很多模型有专属的专项能力，尤其是多模态能力，对应基础认知中的”模态维度”，下面看多模态/垂类类后缀。

4. 多模态/垂类类：体现模型的”专项能力”（对应基础认知：模态维度）

这类后缀代表模型有特定的专项能力，不是通用型模型，能快速区分其定位：

• Vision/V/VL：视觉增强，能识别图片、截图、图表（如GPT-4V）；

• Omni/o：全能多模态，支持文本、图像、音频等全场景（如GPT-4o）；

• Code：代码专用，擅长生成、调试代码，适合编程场景；

• Math：数学专用，擅长公式推导、复杂计算；

• Audio：语音能力，支持语音输入、输出、语音对话。

最后，后缀还能体现模型的版本稳定性，帮我们判断是否适合生产、日常使用等场景，下面拆解测试/特殊类后缀。

5. 测试/特殊类：体现模型的”版本状态”（对应基础认知：全维度适配）

这类后缀能判断模型的稳定性，决定其适用场景：

• Alpha：早期内测版，功能不全、不稳定，仅限内部测试；

• Beta：公测版，功能完整但可能有bug，供用户尝鲜；

• Preview/EXP：预览/实验版，有新功能但不稳定，不建议生产环境使用；

• Stable：稳定版，经过充分测试，适合长期部署；

• Terminus：最终稳定版，该系列停止更新，提供长期支持。

三、新手选型口诀：看完直接用

结合前文基础认知、量化细节和全量后缀解析，我们整理了以下选型口诀，直接对应各类使用场景，新手可直接套用，无需死记硬背复杂知识点。

• 日常用 → 选Instruct/Chat（能听话、能问答）；

• 本地跑 → 选7B+Q4_K_M/GPTQ（体积小、性价比高，Q4_K_M是首选，对应量化章节的中度优化级别）；

• 想保真 → 选Q8_K（8bit+K-Quant算法，接近原版精度，对应量化案例结论）；

• 要快速 → 选Turbo/Flash/Instant（低延迟、高吞吐）；

• 做专业 → 选Max/Ultra/Opus（复杂推理、强能力）；

• 看图片 → 选VL/Omni（视觉增强、多模态）；

• 写代码/算数学 → 选Code/Math/Thinking（专项优化）。

总结

大模型的后缀，本质上是”模型四大核心维度的缩写标识”——Base代表能力基础（能力维度），量化后缀代表部署优化（部署维度），Turbo/Flash代表速度优势（速度维度），VL/Omni代表模态特性（模态维度）。

不用死记硬背，只要记住”按场景选后缀”：想本地部署就看量化相关后缀，想快速响应就选Turbo/Flash，想听话就选Instruct/Chat，结合自己的设备和需求，就能轻松选对适合自己的大模型，真正实现新手快速上手、精准选型。

一、ComfyUI是什么

ComfyUI是一款免费开源、节点式工作流的AI绘图工具，基于Stable Diffusion生态，同时支持SDXL、视频生成等场景。

它和传统网页版AI绘图最大区别：不是固定流水线，而是把AI生成拆成一个个独立Node（节点），像搭积木、接电路一样自由拖拽连线，自定义绘图全流程。

支持Windows、Linux、macOS三大系统，默认本地离线运行，所有模型都需自行下载存到本地，不上传数据，隐私性强；也有官方云端版本可免本地配置使用。

二、三大系统运行优缺点

Windows

优点：安装最简单，一键整合包解压即用；NVIDIA显卡CUDA兼容性拉满，插件和自定义节点生态最全，新手零门槛。

缺点：同配置下显存占用略高，长期批量生成易显存泄漏；AMD显卡仅支持DirectML，运行速度差。

Linux

优点：显存利用率最高、性能最强，比Windows更快更省显存；长期后台批量生成稳定性极佳，AMD显卡可通过ROCm满血运行，适合服务器部署和专业工作室。

缺点：安装需命令行配置环境，新手上手门槛高，部分小众自定义节点适配缺失。

macOS（Apple Silicon M系列）

优点：统一内存架构，大模型不易爆显存；笔记本便携安静、低功耗散热好，自带Metal加速无需额外装驱动。

缺点：无CUDA支持，运行速度比NVIDIA显卡慢；自定义节点、视频生成、多ControlNet兼容性较差，Intel Mac不建议使用。

三、ComfyUI硬件配置要求

四、AI绘图核心名词通俗详解

1. Checkpoint（CKPT大模型）

后缀为.ckpt/.safetensors，体积2-7GB，是AI绘图的全能底子画家。

作用：决定整体画风（写实、二次元、国风等）、画面构图、光影逻辑，更换大模型，整体画风会彻底改变，是运行绘图必须加载的基础模型。

进阶理解：Checkpoint 是把 UNet、CLIP、VAE 三套模型权重完整封装打包在单个文件里的整合模型，内部已包含全套参数，不会从 unet、clip、vae 三个独立文件夹动态加载内容；而独立文件夹存放的是拆分出来的单独模型文件，和 Checkpoint 属于平行格式，互不依赖。新手用 Checkpoint 可一键加载成套匹配好的模型，简单不翻车；进阶玩家则可以单独调用三个独立模型自由混搭，适配 SDXL、Flux 等原生拆分式新模型。

2. VAE

小型调色模型，体积仅几十到几百MB，相当于AI绘图的调色师+美颜滤镜。

作用：AI生成的原始画面是灰蒙蒙的底层潜数据，没有色彩、发雾暗淡；VAE负责校正色彩、提亮通透感、锐化细节、去除噪点，没有合适VAE，生成图片会惨白模糊、观感极差。

3. LoRA

轻量化插件模型，体积20-300MB，不替换基础大模型，只做效果叠加。

作用：可定制固定动漫角色、真人面容、专属画风、服饰穿搭、特定场景，支持多个LoRA混用，还能调节权重强度控制效果深浅。

4. ControlNet

AI构图姿势控制器，强制约束AI绘画不随意发挥。

作用：可精准控制人物骨架动作、画面轮廓线条、场景景深层次、建筑结构布局，给AI打好草稿，牢牢锁定构图和姿态。

5. Embedding

小众特征关键词补丁，体积小巧。

作用：适合AI原生不认识的冷门角色、特殊服饰、小众细节特征，相当于给提示词扩充专属词库，补充LoRA覆盖不到的细微特征。

6. UNET 和 CLIP（了解即可）

CLIP：文本编码器，负责”理解”文字提示词，将其转换为模型能懂的向量，类比于人的大脑。

UNET：图像生成的核心神经网络，负责”执行”绘画，从噪声中重建图像，两者配合完成”理解文字→画出图像”的全过程。

五、ComfyUI基础绘图标准工作流

核心节点流程固定，所有复杂工作流都在此基础上扩展：

1. 加载Checkpoint大模型
2. 可选添加LoRA加载节点，叠加风格人物
3. 输入正向提示词（想要的画面内容）、反向提示词（规避畸形、模糊等瑕疵）
4. 可选接入ControlNet，控制姿势与构图
5. KSampler采样器开始迭代运算，生成底层潜空间数据
6. 通过VAE Decode解码，将灰蒙蒙数据转为正常彩色图片
7. 预览并保存生成图片

整体口诀：加载大模型→加LoRA→写正反提示词→控构图姿势→采样画图→VAE调色出图

六、总结

ComfyUI凭借节点式自由定制、本地离线运行、跨平台适配，成为专业AI创作者首选工具。新手只需弄懂核心模型概念（Checkpoint、VAE、LoRA、ControlNet、Embedding等），掌握基础工作流逻辑，就能从零开始搭建属于自己的AI绘图流水线，无论是日常出图、风格创作，还是批量生成、视频制作都能轻松胜任。

一、使用背景

• 系统：macOS + WSL2
• 核心用途：个人 AI 助手，通过飞书对话
• 主要模型：MiniMax-M2.7（主力）、Qwen3.5-4B-MLX-4bit（本地）

二、配置文件体系

目录结构

所有配置存放在 ~/.hermes/ 目录下：

1
2
3
4
5
6
7
8
9
10

~/.hermes/
├── config.yaml     # 主配置文件（模型、终端、TTS、压缩等）
├── .env             # API Key 和密钥（secrets）
├── auth.json        # OAuth 凭证（Nous Portal 等）
├── SOUL.md          # 主体身份定义（系统提示词 slot #1）
├── memories/        # 持久化记忆（MEMORY.md、USER.md）
├── skills/          # Agent 创建的技能（通过 skill_manage 管理）
├── cron/             # 定时任务
├── sessions/        # 网关会话
└── logs/             # 日志（errors.log、gateway.log — 敏感信息自动脱敏）

三个核心配置文件

配置优先级（从上到下，高优先级覆盖低优先级）

1. CLI 参数 — 例如 hermes chat --model anthropic/claude-sonnet-4（每次调用时覆盖）
2. config.yaml — 所有非密钥配置的主文件
3. .env — 环境变量后备；密钥（API Key、Token、密码）必须放这里
4. 内置默认值 — 以上均未设置时的安全默认值

经验总结

• 标准规则：密钥（API Key、Bot Token、密码）放 .env；其他配置（模型、终端后端、压缩设置、工具集）放 config.yaml
• 标准 api_key 类型 provider（如 minimax-cn、omlx）不走 credential_pool，直接读 .env
• API Key 应只保存在 .env，避免冗余存储
• 配置修改流程：改 config.yaml → hermes doctor --fix → 重启网关

hermes config 命令行

1
2
3
4
5

hermes config                  # 查看当前配置
hermes config edit             # 在编辑器中打开 config.yaml
hermes config set KEY VAL      # 设置指定值（API Key 自动写入 .env，其他写入 config.yaml）
hermes config check            # 检查缺失项（升级后使用）
hermes config migrate          # 交互式添加缺失配置项

技巧：hermes config set 会自动判断写入目标 — API Key 写入 .env，其他写入 config.yaml。

环境变量引用

config.yaml 中支持 ${VAR_NAME} 语法引用环境变量：

1
2
3
4

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

未定义的环境变量保持原样写入（${UNDEFINED_VAR} 不展开）。

三、常见故障与修复

四、日常维护命令

1
2
3
4
5
6
7
8
9
10
11

# 健康检查
hermes doctor

# 自动修复配置
hermes doctor --fix

# 重启网关
hermes gateway restart

# 查看配置
hermes config show

经验总结：

• 修改 config.yaml 后必须先 hermes doctor --fix 再重启
• 重启失败时检查是否有并发进程占用端口
• WSL2 和 macOS 环境下的网关管理命令一致

五、核心功能体系

记忆系统（Memory）

Hermes 有两层持久化记忆：

两个文件均存放在 ~/.hermes/memories/，会话启动时注入系统提示词（冻结快照）。

原理：记忆变更在当前会话不生效（保持 LLM 前缀缓存性能），修改立即持久化到磁盘，下个会话起效。

技能系统（Skills）

技能是按需加载的知识文档，采用渐进式披露节省 token：

1
2
3

Level 0: skills_list() → [{name, description, category}, ...]  (~3k tokens)
Level 1: skill_view(name) → 完整内容 + 元数据
Level 2: skill_view(name, path) → 指定引用文件

技能通过 / 命令直接调用：

1
2
3

/axolotl                    # 加载技能并让 Agent 判断需要什么
/github-pr-workflow         # 直接执行
/plan                       # 加载 plan 技能，检查上下文后写实现计划

技能文件存放在 ~/.hermes/skills/，由 skill_manage 工具管理。

Cron 自动化

定时任务支持：

• 定时触发（0 9 * * *、every 2h 等 cron 表达式）
• 事件触发（webhook）
• 交付目标：飞书、本地文件、或其他平台

六、工具链配置

• TTS/图片/音乐：MiniMax 原生 API（MINIMAX_CN_API_KEY），不依赖 Hermes 内置 fal.ai 的 image_gen
• 本地模型：OMLX（Ollama-MLX），通过 http://127.0.0.1:8000/v1 接入
• Smart Routing：smart_model_routing.enabled: true 开启后，简单任务自动路由到本地免费模型
• browser 工具：设置 cloud_provider: '' 使用本地 agent-browser 模式

七、安全与清理

7.1 安全配置审计

在日常维护中，定期运行安全审计能发现潜在风险。以下是我实际排查发现的问题：

高风险项

中风险项

低风险项

7.2 凭证管理

核心原则：API Key 只保存在 .env，不冗余存储。

实际排查发现 auth.json 中存在 request_count: 0 的凭证，说明从未被使用过。Hermes 运行时实际读取的是 .env 中的环境变量（通过 api_key_env 引用），auth.json 仅作为凭证池缓存层。

维护建议：

• 定期检查 auth.json 中各 provider 的 request_count，及时清理从未使用的凭证
• 保留 copilot（GitHub Copilot）等实际使用的凭证
• 删除冗余凭证：minimax-cn、omlx 等（若实际走 .env）

7.3 Skills 精简

Skills 目录容易积累大量从未使用的技能，定期精简可减少维护负担。

精简标准（个人经验）：

• 优先保留正在使用的 skill（如 github-pr-workflow、hexo-blog-post）
• 删除空目录（仅含 DESCRIPTION.md 无实际内容）
• 删除与当前配置不符的 skill（如无 Modal GPU 需求则删 modal-serverless-gpu）
• 保留视频/音频相关 skill（若业务需要）

实际清理结果：

1
2
3

删除空目录：diagramming/、domain/、email/、feeds/、gaming/、gifs/、inference-sh/、smart-home/、social-media/、note-taking/
删除冗余 skill：modal-serverless-gpu、obliteratus、popular-web-designs
Skills 总数：114 → 约 105 个

7.4 配置精简

config.yaml 也会积累无效配置项，定期清理效果显著。

实际清理数据：

• 初始行数：420 行
• 清理后：约 391 行（减少约 30 行）

删除项：

• 空平台工具集引用：telegram、discord、whatsapp、slack、signal、homeassistant
• 空配置对象：honcho: {}、quick_commands: {}、personalities: {}
• 重复的 delegation 块（patch 错误引入）

7.5 验证流程

清理完成后，按以下顺序验证：

1
2
3
4
5
6
7
8
9
10
11

# 1. 检查配置语法
hermes doctor --fix

# 2. 确认配置生效
hermes config show

# 3. 重启网关
hermes gateway restart

# 4. 验证核心功能
hermes doctor

注意：修改 config.yaml 后必须先运行 hermes doctor --fix 自动修复错误配置，最后再重启网关。

八、推荐的工作流

1. 配置修改前先备份：cp config.yaml config.yaml.backup_日期
2. 用 hermes doctor 验证修改结果
3. 用 hermes config show 确认配置生效
4. 最后 hermes gateway restart
5. 重要决策（如删除 provider、修改认证逻辑）记录到记忆文件

九、使用技巧

来自官方文档的实践建议：

• 明确表达需求：给出具体上下文（文件路径、错误信息、期望行为），减少来回次数
• 前置上下文：一次性提供所有相关信息，胜过多次补充
• 用 Context Files：重复出现的指令（如”use tabs not spaces”）写入 AGENTS.md，Agent 自动读取
• 交给 Agent 探索：说”修复失败的测试”而非”打开 tests/test_foo.py 第 42 行然后…”
• 优先用 Skill：复杂流程先查 /skills，再决定是否自己写提示词
• Cron 自动化重复任务：新闻简报、定时提醒、数据采集等场景优先考虑

前言

接触大模型、多模态AI、向量知识库时，很多人都会被基础概念绕晕：

• Tokenizer到底是什么？
• Token和向量有什么本质区别？
• 图片、音频有没有Tokenizer？
• 不同模型的Token和向量能不能通用？
• 固定维度的向量，为何能装下无穷多知识？

今天用大白话+生活化例子，把底层逻辑一次性讲透，零基础也能轻松看懂。

一、什么是 Tokenizer 和 Token

大模型看不懂汉字、英文、图片、音频，它只认数字。

Tokenizer（分词器）只服务于文本。 作用很简单：

把人类的一句话，拆成最小语义碎片，再给每个碎片分配一个唯一数字ID。

被拆分出来的最小语义碎片，就叫 Token。

举个实际例子：

原句：人工智能改变了生活

Tokenizer拆分后：

1

人工 | 智能 | 改变 | 了 | 生活

再查表编码，变成一串数字：

1

[1024, 1056, 2089, 35, 4120]

几个必备常识

• Token不只是单个汉字，可以是词组、词根、标点、英文片段
• 大模型计费、4K/8K上下文窗口、长度限制，全都按Token算，不是按汉字
• 简易换算参考：1个汉字 ≈ 1.3～1.5 个Token

二、图像、音频也有Token，为什么没有Tokenizer？

大家会疑惑：

多模态大模型里，图片、音频也按Token计费、算上下文，
为什么没有文本这种Tokenizer？

核心真相：两个Token，名字一样，本质完全不同。

多模态Token是这样生成的：

• 图像：大图切成小图块 → 编码器提取特征 → 离散量化成抽象数字编号
• 音频：波形转频谱 → 分帧编码 → 压缩成离散Token

之所以统一叫Token，只是为了适配Transformer架构，统一输入格式、统一计费、统一上下文统计，和文本Tokenizer根本不是一套逻辑。

专业纠正：网上常见说法”把海量影像、图片、文本一起做Tokenizer”，是外行错误表述。Tokenizer只适用于文本；图片、影像、音频不存在传统Tokenizer，正确做法是多模态向量化。

三、Token 与 向量（Embedding）的本质区别

一句话彻底分清：

• Token 是文字的数字编号
• 向量（Embedding） 是内容的语义特征画像

什么是Token

只是一个单纯的整数ID，好比身份证号。只做唯一标识，本身没有任何语义。

比如”猫”编号5201，”狗”编号6892，单看数字，完全看不出它们都属于动物。

什么是向量（Embedding）

是几百至上千维的浮点数数组，好比一个人的性格、爱好、职业档案。

语义越相近的内容，在高维空间里距离越近。
“猫”和”狗”的向量距离，远小于”猫”和”桌子”。

完整流转链路

1
2
3
4
5
6

人类文字
  → Tokenizer
  → Token数字ID
  → 模型嵌入层
  → 高维语义向量
  → 大模型运算推理

实用场景区分

四、不同大模型的Token和向量，能否通用？

结论：完全不通用，互不兼容。

Token编号不统一

每个大模型都有独立专属词表，词表大小、分词规则、子词收录全都不一样。

同样四个字”人工智能”：

• 有的模型拆成4个单字Token
• 有的拆成「人工、智能」2个词组Token

对应的数字ID完全不同。

向量绝不互通

就算巧合下，同一个Token在两个模型编号相同，对应的高维向量数值也完全不一样。每个模型的语义空间都是独立训练的，A模型建好的向量库，直接给B模型完全用不了。

实战铁律：搭建海量图文知识库、RAG系统，一旦选定某个Embedding模型，就不要随意更换，换模型等同于向量库全部作废。

五、同一大模型，向量维度是固定的吗？

同一款大模型，向量维度永久固定。

无论输入：

• 一个字
• 一句话
• 一篇长文
• 一张图片
• 一段音频

最终输出的语义向量，维度完全统一。模型训练完成后，向量维度就被结构写死，不会随意变动。

行业常见维度： 768维、1024维、4096维、8192维。

规律很简单：模型规模越大，向量维度越高，语义区分能力越精细。

六、终极疑问：参数有限、维度固定，为何能表达无穷知识？

很多人都有这个困惑：大模型只有几十亿、几百亿参数，向量维度又是固定的，为什么能承载远超参数数量的文字、图片和海量知识？

底层核心逻辑：高维向量靠组合爆炸表达语义，不是一一对应存储。

• 向量每一维都是连续浮点数，取值近乎无限
• 语义由所有维度联合组合表达，不是一个维度对应一种含义
• 固定维度的高维空间，能表达的独立语义是天文数字，远超模型总参数量

通俗比喻：

• 模型参数，只是搭建高维空间的框架骨架，数量有限
• 高维向量，是空间里的无数特征坐标

依靠维度组合变化，就能容纳近乎无限的语义与知识，根本不需要给每条知识，单独占用一个参数。

七、全文核心总结

1. Tokenizer仅适用于文本，图片、音频没有传统Tokenizer
2. Token是无语义的编号，向量是承载语义的高维特征
3. 不同大模型的Token编号、向量语义空间，完全不互通
4. 同一模型所有内容向量维度固定，模型越大维度通常越高
5. 有限参数搭建高维空间，靠组合爆炸承载无穷语义
6. 海量图文影像资料治理，不用做Tokenizer，正确方案是多模态向量化

在 AI Agent 的长期协作中，上下文管理是决定智能体能力上限的核心瓶颈。传统方案要么因窗口限制导致“失忆”，要么因全量传输造成 Token 成本爆炸。本文将基于 OpenClaw 文档与社区实践，详解 Lossless-Claw（LCM）与 QMD 的无损上下文组合方案，从原理、价值到可直接复制的实操配置，全部经过官方文档与经验验证。

一、为什么做：三大痛点

1.1 滑动窗口失忆

OpenClaw 内置的上下文压缩机制存在一个根本性缺陷：它是有损的（lossy）。当对话超过模型上限（如 8k/16k Token），早期信息直接被截断，AI 彻底“忘记”前期需求、代码细节和关键决策。内置压缩还会把数十轮对话压成一段几百 Token 的摘要，不保留原始消息，压缩后细节永远丢失。

1.2 Token 成本雪崩

长对话全量传输，每轮请求 Token 数指数级增长。经验显示，长对话场景下单次请求可能携带 8 万 + tokens，不仅响应延迟高达 45 秒，API 成本可达 $2.4/次。

1.3 缺乏可定制性

传统压缩规则硬编码在核心中，插件无法介入。近期 OpenClaw 版本开始支持可插拔上下文引擎，新增 ContextEngine 插槽与生命周期钩子，使插件可以在上下文生成、压缩、拼接以及子 Agent 管理的各个阶段介入。OpenClaw 文档支持 lossless-claw 插件——基于 Voltropy 团队 LCM 论文的无损上下文方案。

1.4 破局：Lossless-Claw + QMD

这套组合是 OpenClaw 社区中广泛采用的无损上下文方案，核心价值在于分工明确、互补增效：

• Lossless-Claw（LCM） ：负责当前会话内存。用 DAG 分层摘要 + SQLite 全量持久化，对话再长也不丢原始消息，同时把活跃上下文压缩到模型窗口 75% 以内。
• QMD：负责跨会话硬盘记忆。本地语义搜索引擎，只提取最相关的 2-3 句话注入上下文，杜绝全库扫描的 Token 浪费。

LCM 管“当下对话不中断”，QMD 管“历史知识不丢失” ，两者结合实现“永久记忆 + 零成本膨胀”。

1.5 预期效果对比

| 指标 | 原生 OpenClaw | Lossless-Claw + QMD | 提升 |
|: —|: —|: —|: —|
| 上下文大小 | 5000+ Token（溢出） | 800-1200 Token | 削减 75%-85% |
| 历史追溯 | 无法恢复早期消息 | 100% 无损展开 | 永久记忆 |
| 响应速度 | 8-10 秒 | 1-2 秒 | 提速 80%+ |
| Token 成本 | 100 轮 ≈ 50 万 Token | 100 轮 ≈ 5 万 Token | 节省 90% |
| OOLONG 得分 | Claude Code 70.3 | lossless-claw 74.8 | 击败默认方案 |

在 OOLONG 长上下文推理基准测试中，相同模型（Claude Opus 4.6）搭配 lossless-claw 后得分从 70.3 提升至 74.8，Token 消耗降低 30%+。QMD 端 Token 削减达 60-97%（平均 95% 以上），响应速度提升 5-50 倍，成本降低 90-99%，精准度高达 93%。

二、是什么：双引擎架构解析

2.1 Lossless-Claw：DAG 无损上下文管理

Lossless Claw（LCM）是一个为 OpenClaw 开发的无损上下文管理插件，基于 DAG（有向无向图）结构的摘要系统替代 OpenClaw 内置的滑动窗口压缩机制。它不在上下文爆满后临时补救，而是持续在后台异步处理历史消息。首先将所有原始消息完整写入 SQLite 数据库，不主动丢弃任何内容；随后将较旧的消息分块，调用 LLM 生成摘要；这些摘要被组织成 DAG 结构——底层节点保留时序细节，上层节点逐步浓缩为高层级摘要，既能控制上下文体积，又不会真正失去原始信息。

LCM 的核心架构包含两大层次：

• 持久化存储：所有对话消息、工具调用记录、文件内容均存入 SQLite 数据库，永不主动删除，作为不可变的原始副本。
• DAG 摘要层：超出最新 N 条消息后，异步生成 Leaf 层级摘要；同层摘要积累到阈值后向上凝练，形成层级化 DAG 结构。每个摘要都链接回它的源消息——这就是“无损”的含义。

LCM 通过五个关键操作完成工作：将每条消息持久化到 SQLite 数据库；将旧消息分块摘要；随着摘要积累，进一步浓缩为更高层级节点，形成 DAG；每轮通过组合摘要 + 近期原始消息来组装上下文；并提供 lcm_grep、lcm_describe、lcm_expand 等工具，让 Agent 可以搜索和回忆已压缩历史中的细节。

OpenClaw 核心开发者 Josh Lehman 在亲身测试后的评价：“对话感觉永远不会丢失信息（因为某种程度上确实不会），始终在 30-100K Token 范围内运行，零维护。”

2.2 QMD：本地语义搜索引擎

QMD（Quantum Memory Database）是由 GitHub 用户 tobi 开发的本地语义搜索引擎。它的核心理念是：不要把整个文件塞给 AI，而是先用本地搜索找到最相关的片段（通常只有 2-3 句话），再把这些精准内容传给 AI。

QMD 采用三层混合检索机制：

1. BM25 全文搜索：精准匹配端口、变量名、文件名等精确术语；
2. 向量语义搜索：理解概念关联（如“服务器配置”与“部署网关”的同义表述）；
3. LLM 重排序：轻量模型二次筛选，确保最相关片段优先。

QMD 的核心特性：完全本地运行，所有模型、数据、索引都不上云；混合搜索（BM25 + 向量语义 + LLM 重排序）；不消耗任何 API 配额，自带模型；支持 MCP 协议，专为 AI 工作流设计。

OpenClaw 文档将其列为支持的 memory backend，定位为 Local-first sidecar，具备重排序（reranking）、查询扩展（query expansion）以及索引工作区外目录的能力。

2.3 协同工作流

• 写入：LCM 将每一轮对话、每一次工具调用、每一个决策都完整写入 SQLite 数据库，并异步构建 DAG 摘要层，确保信息永不丢失。
• 检索：QMD 通过向量检索从长期记忆中精准召回最相关的片段，避免把整个历史上下文塞给模型。
• 巩固：配合 OpenClaw 内置的 Dreaming 梦境系统（模拟人类睡眠的记忆巩固过程），三者形成“写入 → 巩固 → 检索”的完整记忆闭环。

三、怎么做：完整配置指南

⚠️ 前置条件：OpenClaw 版本需 ≥ 2026.3.7（lossless-claw 要求）且 ≥ 2026.2.2（QMD 要求）。用 openclaw --version 检查版本。

3.1 安装 Lossless-Claw

第一步：检查前置条件

• 已安装支持插件上下文引擎的 OpenClaw（≥ 2026.3.7）；
• Node.js 版本为 22 或更高；
• 已在 OpenClaw 中配置好可用于摘要生成的 LLM 提供方；
• 强烈建议 Node 运行环境支持 SQLite FTS5 编译选项。

第二步：安装插件

使用官方插件安装命令：

1

openclaw plugins install @martian-engineering/lossless-claw

该命令会下载插件、登记配置，并在系统中启用 lossless-claw。OpenClaw 会优先从 ClawHub 拉取，自动回退到 npm。

第三步：将 lossless-claw 设为默认上下文引擎

编辑配置文件 ~/.openclaw/openclaw.json，确保 contextEngine 指向 lossless-claw：

1
2
3
4
5
6
7

{
  "plugins": {
    "slots": {
      "contextEngine": "lossless-claw"
    }
  }
}

第四步：调整进阶参数（可选）

在 openclaw.json 的 plugins.entries 中添加 lossless-claw 的详细配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "plugins": {
    "entries": {
      "lossless-claw": {
        "enabled": true,
        "config": {
          "freshTailCount": 32,
          "contextThreshold": 0.75,
          "incrementalMaxDepth": -1,
          "summaryModel": "openai/gpt-5.4-mini"
        }
      }
    }
  }
}

参数说明：

• freshTailCount: 32：保护最近 32 条消息不被压缩，保持短期上下文连贯。
• contextThreshold: 0.75：当上下文占用达到 75% 时启动压缩流程，为模型回复预留空间。
• incrementalMaxDepth: -1：允许摘要树无限制扩展，让长期记忆自然增长。
• summaryModel：将压缩摘要绑定到指定模型（本配置使用 openai/gpt-5.4-mini）。

第五步：重启服务

1

openclaw gateway restart

3.2 安装 QMD

第一步：安装 QMD CLI

方式一（推荐，使用 npm）：

1

npm i -g @tobilu/qmd

方式二（使用 Bun，速度更快）：

1
2
3
4
5

# 先装 Bun
curl -fsSL https://bun.sh/install | bash
# 装 Qmd
bun install -g @tobilu/qmd
sudo ln -s $(which qmd) /usr/local/bin/qmd

第二步：首次运行自动下载模型

首次运行 QMD 时，会自动下载默认模型文件，通常包括 embeddinggemma 和 query-expansion 相关 GGUF 模型，整体约 1.5GB 左右。首次启动会比后续运行慢，并且需要等待模型下载完毕后才能进入正常索引。

⚠️ 常见问题：模型文件名不匹配

QMD 运行时可能因文件名大小写问题找不到模型，需手动创建软链接：

1
2

cd ~/.cache/qmd/models
ln -sf hf_ggml-org_embeddinggemma-300M-Q8_0.gguf local:embeddinggemma-300m-qat-Q8_0.gguf

第三步：配置 OpenClaw 使用 QMD

编辑 ~/.openclaw/openclaw.json，在 memory 段添加 QMD 配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "searchMode": "query",
      "includeDefaultMemory": true,
      "update": {
        "interval": "5m",
        "debounceMs": 15000,
        "onBoot": true
      },
      "sessions": {
        "enabled": true,
        "retentionDays": 30
      },
      "limits": {
        "maxResults": 6,
        "maxSnippetChars": 600,
        "timeoutMs": 120000
      },
      "scope": {
        "default": "deny",
        "rules": [
          {
            "action": "allow",
            "match": {
              "chatType": "direct"
            }
          }
        ]
      },
      "paths": [
        {
          "name": "blogs",
          "path": "/Users/sean/note/haies.cn/source/_posts",
          "pattern": "**/*.md"
        },
        {
          "name": "wans",
          "path": "/Users/sean/note/wans",
          "pattern": "**/*.md"
        }
      ]
    }
  }
}

参数说明：

• backend: "qmd"：启用 QMD 记忆后端。
• searchMode: "query"：混合搜索（语义 + 关键词，最准）。可选 search（纯关键词，最快）或 vsearch（纯语义搜索）。
• paths：配置需要索引的外部路径，支持多个目录。
• maxResults: 6：最大返回结果数，越多越耗 Token。
• scope.default: "deny" + rules：默认关闭记忆，仅允许私聊使用。

第四步：初始化 QMD 索引并生成向量嵌入

1
2
3
4
5

# 首次索引（自动扫描 paths 中配置的路径）
qmd index

# 生成向量嵌入（提升搜索精度，必须执行）
qmd embed

💡 建议定期运行 qmd embed（如每天一次）以确保新增文档可被向量检索。

3.3 验证配置

验证 Lossless-Claw：

1
2
3
4
5
6
7

# 检查插件列表
openclaw plugins list
# 预期输出包含 @martian-engineering/lossless-claw

# 检查上下文引擎配置
openclaw config get plugins.slots.contextEngine
# 预期输出："lossless-claw"

验证 QMD：

1
2
3
4
5
6

# 查看 QMD 版本
qmd --version

# 检查 OpenClaw 记忆健康状态
openclaw memory status
# 预期看到 Indexed、Store、Vector 状态正常

联合验证：

1

openclaw memory status

若输出正常，说明两套系统均已就绪。也可以运行 openclaw memory search "测试关键词" 测试搜索功能。

3.4 验证清单

示例验证结果（2026-04-10）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# LCM 状态
$ openclaw logs --limit 50 | grep lossless
2026-04-09T16:08:23.838Z info {"plugin":"lossless-claw"} [lcm] Plugin loaded (enabled=true, db=/Users/sean/.openclaw/lcm.db, threshold=0.75)

$ sqlite3 ~/.openclaw/lcm.db "SELECT COUNT(*) FROM summaries; SELECT COUNT(*) FROM messages;"
159
7855

# QMD 状态
$ qmd status
Documents
  Total:    537 files indexed
  Vectors:  1882 embedded
  Pending:  0

Collections
  blogs (qmd://blogs/): 42 files
  wans (qmd://wans/): 26 files
  memory (qmd://memory/): 275 files
  sessions-main (qmd://sessions-main/): 68 files

# 搜索测试
$ qmd search "docker" -c blogs -n 3
qmd://blogs/docker.md:2 #637513 - Score: 85%
qmd://blogs/containerd.md:8 #7d32a7 - Score: 83%
qmd://blogs/geoserver.md:11 #cff5cb - Score: 83%

四、高级优化与故障排除

4.1 黄金参数调优

4.2 成本优化策略

• 摘要模型降级：使用 claude-haiku-4-5 或本地 ollama/llama-3:8b 执行摘要，主对话保持高级模型。
• 排除噪音会话：通过 ignoreSessionPatterns 过滤 cron job、心跳检测等无状态会话。

4.3 常见问题排查

Q1：配置后 AI 仍“失忆”

1
2
3
4
5

# 检查 contextEngine 是否指向 lossless-claw
openclaw config get plugins.slots.contextEngine
# 若未指向，执行：
openclaw config set plugins.slots.contextEngine "lossless-claw"
openclaw gateway restart

Q2：Token 消耗未降低

1
2
3
4

# 检查 freshTailCount 是否过大
openclaw config get plugins.entries.@martian-engineering/lossless-claw.LCM_FRESH_TAIL_COUNT
# 建议调整为 32，并降低阈值：
openclaw config set plugins.entries.@martian-engineering/lossless-claw.LCM_CONTEXT_THRESHOLD 0.6

Q3：QMD 搜索超时或无结果

1
2
3
4
5

// 调整 openclaw.json 中的超时设置
"limits": {
  "timeoutMs": 8000,   // 从 4000 增加到 8000
  "maxResults": 4      // 减少结果数以降低负载
}

若完全无结果，检查索引是否已生成：qmd embed。

Q4：QMD 模型文件未找到

1
2
3
4
5
6

# 检查模型文件
ls -la ~/.cache/qmd/models/

# 如发现文件名不匹配，创建软链接
cd ~/.cache/qmd/models
ln -sf hf_ggml-org_embeddinggemma-300M-Q8_0.gguf local:embeddinggemma-300m-qat-Q8_0.gguf

Q5：SQLite 权限错误（Linux/Docker）

1
2

sudo chmod -R 775 ~/.openclaw/data
sudo chown -R $(whoami):$(whoami) ~/.openclaw/data

五、总结

Lossless-Claw + QMD 是 OpenClaw 社区中广泛使用的无损上下文组合方案，可以有效缓解“失忆、成本、精度”三大痛点。通过 LCM 的 DAG 无损压缩与 QMD 的本地精准检索，目标是实现永久记忆 + Token 膨胀可控 + 更平稳的响应时间。

两者分工明确、互补增效：LCM 负责“当下对话不中断”，QMD 负责“历史知识不丢失”，配合 OpenClaw 内置的 Dreaming 梦境系统，形成“写入 → 巩固 → 检索”的完整记忆闭环。在一些测试中表明：在一些长上下文场景中，得分和成本都有明显改善，但实际结果仍依赖具体模型、主题和配置。

本文中的配置、命令和参数基于 OpenClaw、LCM、QMD 的官方文档或社区资料整理，可作为可复制的参考。按此配置，你的 OpenClaw 能更好地支持长期对话与历史记忆场景。

官方参考

• Lossless-Claw GitHub：https://github.com/Martian-Engineering/lossless-claw
• QMD GitHub：https://github.com/tobi/qmd
• OpenClaw 官方文档：https://docs.openclaw.ai
• OpenClaw Context Engine：https://docs.openclaw.ai/concepts/context-engine
• OpenClaw Memory Overview：https://docs.openclaw.ai/concepts/memory

在 OpenClaw 中集成 LiteLLM Proxy，通过其自定义 Hook 实现「本地小模型处理简单问题＋云端思考型大模型处理复杂问题」的自动路由。复杂度路由是 LiteLLM 的功能，不是 OpenClaw 原生能力。

环境状态：OpenClaw v2026.4.1、oMLX、Qwen3.5-4B-MLX-4bit 已安装完成。
重要说明：复杂度智能路由通过 LiteLLM 的 async_pre_call_hook 实现，OpenClaw 本身不支持基于任务复杂度自动选择模型的功能。

OpenClaw 原生路由能力分析

OpenClaw 原生路由能力（v2026.4.1）

为什么选择 LiteLLM 方案？

flowchart TD
    subgraph OpenClaw原生["OpenClaw 原生路由能力"]
        A1["1️⃣ 多代理路由<br/>(Multi-Agent Routing)"] --> A1_result{✓ 根据用户/频道路由到不同 Agent<br/>✗ 不能根据任务复杂度选择模型}
        A2["2️⃣ 模型故障转移<br/>(Model Failover)"] --> A2_result{✓ 模型失败时切换备用模型<br/>✗ 简单的轮询/列表切换<br/>不考虑任务复杂度}
        A3["3️⃣ 复杂度智能路由<br/>(Complexity Routing)"] --> A3_result{✗ OpenClaw 完全不支持<br/>✓ 需要通过 LiteLLM Custom Hook 实现}
    end

LiteLLM vs OpenClaw 原生功能对比

结论：OpenClaw 原生路由主要用于多代理场景（不同用户/频道使用不同 Agent），而非复杂度路由（根据任务难度选择模型）。真正的智能路由必须依赖 LiteLLM 的 Custom Hook。

核心价值

通过 LiteLLM Proxy + 自定义 Hook 实现真正的本地+云端复杂度智能路由：

flowchart TB
    A["用户请求"] --> B["OpenClaw Gateway"]
    B --> C["LiteLLM Proxy<br/>(复杂度路由层)"]
    C --> D["async_pre_call_hook<br/>(复杂度分析)"]

    D --> D1["Token 数量统计"]
    D --> D2["关键词模式匹配"]
    D --> D3["复杂度评分算法"]

    D1 --> E{评分 ≥ 阈值?}
    D2 --> E
    D3 --> E

    E -->|是| F["astron-code-latest<br/>(云端)"]
    E -->|否| G["qwen-local<br/>(本地)"]

    F --> H["云端模型<br/>Astron Code<br/>(深度推理)"]
    G --> I["本地模型<br/>oMLX Qwen3.5-4B<br/>(毫秒响应)"]

核心优势：

• 真正的复杂度路由：自动根据任务复杂度选择模型（LiteLLM Hook 功能）
• 零成本处理简单任务：本地模型响应简单查询
• 智能故障转移：模型不可用时自动切换
• 统一成本追踪：集中查看所有模型消费

一、架构概述

flowchart TB
    subgraph OpenClaw["OpenClaw Gateway (v2026.4.1 + skill-vetter)"]
        A["用户请求"]
    end

    A -->|/v1/chat/completions| B["LiteLLM Proxy<br/>(localhost:4000 复杂度路由层)"]

    subgraph LiteLLM["LiteLLM Proxy"]
        direction TB
        C["complexity_router.py<br/>• 复杂度评分算法<br/>• 关键词匹配<br/>• 模型路由决策"]
        D["config.yaml<br/>• 模型列表定义<br/>• 故障转移规则<br/>• Hook 注册"]
    end

    B --> C
    B --> D

    C --> E{"模型选择"}
    E -->|简单任务| F["本地模型"]
    E -->|复杂任务| G["云端模型"]

    subgraph Local["本地模型"]
        F1["oMLX Qwen3.5-4B-MLX<br/>(localhost:8000)<br/>• 零成本<br/>• 毫秒级响应"]
    end

    subgraph Cloud["云端模型"]
        G1["Astron Code / Claude / GPT-4<br/>(api.astron.com 等)<br/>• 按量计费<br/>• 深度推理能力"]
    end

    F --> F1
    G --> G1

重要说明：复杂度路由完全由 LiteLLM Proxy 的自定义 Hook 实现，OpenClaw 仅作为统一的 AI agent 网关。

二、LiteLLM Proxy 安装

1
2
3
4
5
6
7
8
9
10

# 安装 LiteLLM Proxy (带完整依赖)
pip install 'litellm[proxy]'

# 或使用 Docker
docker run \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v $(pwd)/complexity_router.py:/app/complexity_router.py \
  -e DEEPSEEK_API_KEY="your-deepseek-key" \
  -p 4000:4000 \
  ghcr.io/berriai/litellm:main-latest

三、复杂度路由 Hook 实现

这是核心组件，实现基于 prompt 复杂度的智能路由。

重要说明：此复杂度路由器是 LiteLLM 的自定义 Hook，不是 OpenClaw 的原生功能。需要先配置 LiteLLM Proxy，然后 OpenClaw 连接到已配置好的 Proxy。

3.1 创建复杂度路由器

创建 ~/.openclaw/litellm/complexity_router.py：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

"""
LiteLLM 复杂度路由 Hook
根据 prompt 复杂度自动选择本地或云端模型

注意：此功能完全由 LiteLLM 实现，OpenClaw 本身不支持复杂度路由

简单任务 → 本地模型 (oMLX Qwen3.5-4B) - 零成本，毫秒响应
复杂任务 → 云端模型 (DeepSeek Reasoner) - 深度推理能力
"""

import re
from typing import Any, Dict, Literal, Optional
from litellm.integrations.custom_logger import CustomLogger
from litellm.types.utils import ModelResponse
import litellm

class ComplexityRouter(CustomLogger):
    """
    复杂度路由器：根据 prompt 特征自动选择模型
    """

    def __init__(self):
        super().__init__()
        # 复杂度阈值：分数 >= threshold 路由到云端
        self.threshold = 2

        # 复杂任务关键词
        self.complex_keywords = [
            # 中文复杂任务
            "分析", "比较", "设计", "架构", "推理", "证明", "评估", "总结",
            "深度", "详细", "全面", "系统", "研究", "解释原因", "为什么",
            "如何实现", "如何解决", "论述", "阐述", "评估", "判断",
            # 英文复杂任务
            "analyze", "compare", "design", "architect", "reason", "prove",
            "evaluate", "synthesize", "comprehensive", "detailed", "explain why",
            "how to implement", "discuss", "assess", "critical thinking",
            # 数学/逻辑
            "计算", "推导", "求解", "证明", "calculate", "derive", "solve",
            # 代码相关
            "debug", "optimize", "refactor", "重构", "优化", "调试"
        ]

        # 简单任务关键词
        self.simple_keywords = [
            "你好", "hi", "hello", "嗨", "hey",
            "谢谢", "thanks", "thank you",
            "查询", "look up", "search",
            "翻译", "translate",
            "今天", "天气", "时间", "日期", "today", "weather", "time", "date",
            "问候", "greeting", "打招呼",
            "简单", "easy", "simple",
            "是什么", "what is", "who is", "define"
        ]

    def _calculate_complexity_score(self, text: str) -> int:
        """
        计算 prompt 复杂度分数
        返回值越高表示越复杂
        """
        score = 0
        text_lower = text.lower()

        # 1. Token 数量 (粗略估算)
        tokens = len(text.split())
        if tokens > 1000:
            score += 4
        elif tokens > 500:
            score += 3
        elif tokens > 200:
            score += 2
        elif tokens > 50:
            score += 1

        # 2. 复杂任务关键词匹配
        for keyword in self.complex_keywords:
            if keyword.lower() in text_lower:
                score += 1

        # 3. 简单任务关键词匹配
        for keyword in self.simple_keywords:
            if keyword.lower() in text_lower:
                score -= 2

        # 4. 代码/技术内容判断
        code_indicators = ["```", "def ", "class ", "function", "import ",
                          "代码", "code", "python", "javascript", "api"]
        for indicator in code_indicators:
            if indicator in text_lower:
                score += 1

        # 5. 问号数量（提问复杂度）
        question_count = text.count('?') + text.count('？')
        if question_count >= 3:
            score += 2
        elif question_count >= 1:
            score += 1

        # 6. 否定简单问候
        greeting_patterns = [
            r'^你好[吗呀啊]?', r'^hi\s*$', r'^hello\s*$', r'^hey\s*$',
            r'^嗨[吗呀啊]?', r'^嗨$'
        ]
        for pattern in greeting_patterns:
            if re.match(pattern, text.strip(), re.IGNORECASE):
                score = -10  # 强制为简单任务

        return score

    async def async_pre_call_hook(
        self,
        user_api_key_dict: Any,
        cache: Any,
        data: Dict,
        call_type: Literal["completion", "text_completion", "embeddings",
                          "image_generation", "moderation", "audio_transcription"]
    ) -> Dict:
        """
        LiteLLM Pre-Call Hook
        在请求发送到模型之前修改模型选择

        Args:
            user_api_key_dict: 用户 API 密钥信息
            cache: 缓存实例
            data: 请求数据 (包含 messages, model 等)
            call_type: 调用类型

        Returns:
            修改后的 data (其中 model 字段被替换)
        """
        # 只处理 completion 调用
        if call_type != "completion":
            return data

        # 提取文本内容
        messages = data.get("messages", [])
        text_content = ""

        for message in messages:
            if isinstance(message, dict):
                content = message.get("content", "")
                if isinstance(content, str):
                    text_content += content + " "
            elif isinstance(message, str):
                text_content += message + " "

        # 计算复杂度分数
        complexity_score = self._calculate_complexity_score(text_content)

        # 路由决策
        if complexity_score >= self.threshold:
            # 复杂任务 → 云端推理模型
            target_model = "astron-code-latest"
            route_reason = f"complex (score={complexity_score})"
        else:
            # 简单任务 → 本地模型
            target_model = "qwen-local"
            route_reason = f"simple (score={complexity_score})"

        # 记录路由决策
        print(f"[ComplexityRouter] {route_reason} → {target_model}")
        print(f"[ComplexityRouter] Text preview: {text_content[:100]}...")

        # 修改请求中的模型
        data["model"] = target_model

        return data

# 创建全局实例供 config.yaml 引用
complexity_router_instance = ComplexityRouter()

3.2 复杂度评分说明

示例：

3.3 工具感知路由（Tool-Aware Routing）

OpenClaw 的核心能力是工具调用（Function Calling），不同工具对模型能力要求差异巨大。以下是工具场景的路由建议：

工具类型与模型匹配矩阵

工具感知路由流程图

flowchart TD
    A["用户请求"] --> B{检测工具调用意图?}

    B -->|无| C{文本复杂度评估}
    C -->|简单| C1["qwen-local<br/>(本地)"]
    C -->|复杂| C2["astron-code-latest<br/>(云端)"]

    B -->|是| D{"工具类型?"}

    D -->|简单查询/文件读取| E["qwen-local<br/>(本地)"]
    D -->|文件编辑/网页操作| F["astron-code-latest<br/>(云端)"]
    D -->|代码调试/架构设计| G["astron-code-latest<br/>(云端)"]
    D -->|多工具编排| H["astron-code-latest<br/>(云端)"]

    C1 --> Z["返回结果"]
    C2 --> Z
    E --> Z
    F --> Z
    G --> Z
    H --> Z

增强版复杂度路由器

更新 complexity_router.py 以支持工具感知路由：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225

"""
LiteLLM 增强版复杂度路由 Hook
支持工具感知路由，根据任务类型和复杂度自动选择模型

路由策略：
- 简单任务 → 本地模型 (oMLX Qwen3.5-4B)
- 工具操作 → 根据工具类型选择
- 复杂推理 → 云端推理模型 (DeepSeek Reasoner)
"""

import re
import json
from typing import Any, Dict, Literal, Optional, List
from litellm.integrations.custom_logger import CustomLogger
from litellm.types.utils import ModelResponse
import litellm

class EnhancedComplexityRouter(CustomLogger):
    """
    增强版复杂度路由器：支持工具感知的智能路由
    """

    def __init__(self):
        super().__init__()

        # 复杂度阈值
        self.text_threshold = 2

        # 工具类型与模型映射
        self.tool_model_mapping = {
            # 简单工具 → 本地模型
            "simple": {
                "tools": [
                    "weather", "time", "date", "calculator", "simple_search",
                    "read_file", "list_directory", "get_time", "currency_convert"
                ],
                "model": "qwen-local"
            },
            # 中等复杂度 → 云端聊天模型
            "medium": {
                "tools": [
                    "write_file", "edit_file", "web_search", "web_scrape",
                    "image_generation", "document_parser", "api_call",
                    "send_message", "create_reminder"
                ],
                "model": "astron-code-latest"
            },
            # 高复杂度 → 云端推理模型
            "complex": {
                "tools": [
                    "debug", "code_review", "architecture_design", "security_audit",
                    "multi_agent", "workflow_orchestration", "data_analysis",
                    "report_generation", "research_synthesis"
                ],
                "model": "astron-code-latest"
            }
        }

        # 复杂任务关键词
        self.complex_keywords = [
            "分析", "比较", "设计", "架构", "推理", "证明", "评估", "总结",
            "深度", "详细", "全面", "系统", "研究", "解释原因", "为什么",
            "如何实现", "如何解决", "论述", "阐述", "判断",
            "analyze", "compare", "design", "architect", "reason", "prove",
            "evaluate", "synthesize", "comprehensive", "debug", "optimize"
        ]

        # 简单任务关键词
        self.simple_keywords = [
            "你好", "hi", "hello", "嗨", "hey",
            "谢谢", "thanks", "查询", "翻译", "天气", "时间",
            "问候", "打招呼", "是什么", "what is", "define"
        ]

    def _detect_tool_intent(self, text: str, messages: List[Dict]) -> Optional[str]:
        """
        检测是否有工具调用意图
        返回工具类型：simple, medium, complex, 或 None
        """
        text_lower = text.lower()

        # 检查最后一条用户消息是否暗示使用工具
        tool_indicators = {
            "simple": [
                "查一下天气", "现在几点了", "今天多少号", "帮我算一下",
                "weather", "time", "date", "what time is it"
            ],
            "medium": [
                "帮我写一个文件", "搜索一下", "查找网页", "发消息",
                "write", "search", "scrape", "send", "create file",
                "帮我发送", "生成图片"
            ],
            "complex": [
                "帮我debug", "代码审查", "架构设计", "安全审计",
                "帮我分析这段代码", "多步骤完成", "自动执行",
                "debug", "review", "architect", "audit", "analyze code",
                "帮我规划", "research"
            ]
        }

        for level, indicators in tool_indicators.items():
            for indicator in indicators:
                if indicator.lower() in text_lower:
                    return level

        # 检查消息历史中是否有工具调用
        for msg in messages[-3:]:  # 检查最近3条消息
            if isinstance(msg, dict):
                content = msg.get("content", "")
                tool_calls = msg.get("tool_calls", [])
                if tool_calls:
                    # 有工具调用，检查工具名称
                    for call in tool_calls:
                        func_name = call.get("function", {}).get("name", "").lower()
                        for level, config in self.tool_model_mapping.items():
                            if func_name in config["tools"]:
                                return level

        return None

    def _calculate_complexity_score(self, text: str) -> int:
        """
        计算纯文本复杂度分数
        """
        score = 0
        text_lower = text.lower()

        # 1. Token 数量
        tokens = len(text.split())
        if tokens > 1000:
            score += 4
        elif tokens > 500:
            score += 3
        elif tokens > 200:
            score += 2
        elif tokens > 50:
            score += 1

        # 2. 复杂关键词
        for keyword in self.complex_keywords:
            if keyword.lower() in text_lower:
                score += 1

        # 3. 简单关键词
        for keyword in self.simple_keywords:
            if keyword.lower() in text_lower:
                score -= 2

        # 4. 问号数量
        question_count = text.count('?') + text.count('？')
        if question_count >= 3:
            score += 2
        elif question_count >= 1:
            score += 1

        # 5. 问候检测
        greeting_patterns = [
            r'^你好[吗呀啊]?', r'^hi\s*$', r'^hello\s*$', r'^hey\s*$'
        ]
        for pattern in greeting_patterns:
            if re.match(pattern, text.strip(), re.IGNORECASE):
                score = -10

        return score

    def _select_model_for_tool(self, tool_level: str) -> str:
        """
        根据工具类型选择模型
        """
        if tool_level in self.tool_model_mapping:
            return self.tool_model_mapping[tool_level]["model"]
        return "astron-code-latest"  # 默认使用云端聊天模型

    async def async_pre_call_hook(
        self,
        user_api_key_dict: Any,
        cache: Any,
        data: Dict,
        call_type: Literal["completion", "text_completion", "embeddings",
                          "image_generation", "moderation", "audio_transcription"]
    ) -> Dict:
        """
        LiteLLM Pre-Call Hook
        支持工具感知的智能路由
        """
        if call_type != "completion":
            return data

        messages = data.get("messages", [])
        text_content = ""

        for message in messages:
            if isinstance(message, dict):
                content = message.get("content", "")
                if isinstance(content, str):
                    text_content += content + " "
            elif isinstance(message, str):
                text_content += message + " "

        # 1. 首先检测工具调用意图
        tool_level = self._detect_tool_intent(text_content, messages)

        if tool_level:
            # 工具感知路由
            target_model = self._select_model_for_tool(tool_level)
            route_reason = f"tool-{tool_level}"
            print(f"[EnhancedRouter] {route_reason} → {target_model}")
        else:
            # 2. 纯文本复杂度路由
            complexity_score = self._calculate_complexity_score(text_content)

            if complexity_score >= self.text_threshold:
                target_model = "astron-code-latest"
                route_reason = f"complex-text (score={complexity_score})"
            else:
                target_model = "qwen-local"
                route_reason = f"simple-text (score={complexity_score})"

            print(f"[EnhancedRouter] {route_reason} → {target_model}")

        data["model"] = target_model
        return data

# 创建全局实例
enhanced_router_instance = EnhancedComplexityRouter()

工具场景路由示例

工具成本优化策略

对比全云端方案：全部使用 astron-code-latest，月成本约 $100，节省 60%。

四、LiteLLM 配置文件

创建 ~/.openclaw/litellm/config.yaml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# ===========================================
# 模型列表定义
# ===========================================
model_list:
  # ─────────────────────────────────────────
  # 本地模型：oMLX Qwen3.5-4B
  # ─────────────────────────────────────────
  - model_name: qwen-local
    litellm_params:
      model: openai/qwen3.5-4b
      api_base: http://localhost:8000/v1
      api_key: "omlx-local"
      rpm: 60
    model_info:
      mode: chat
      supports_function_calling: false
      supports_vision: false

  # ─────────────────────────────────────────
  # 云端模型：DeepSeek
  # ─────────────────────────────────────────
  - model_name: astron-code-latest
    litellm_params:
      model: deepseek/astron-code-latest
      api_key: os.environ/DEEPSEEK_API_KEY
      rpm: 60
    model_info:
      mode: chat
      supports_function_calling: true

  - model_name: astron-code-latest
    litellm_params:
      model: deepseek/astron-code-latest
      api_key: os.environ/DEEPSEEK_API_KEY
      rpm: 10
    model_info:
      mode: chat
      supports_function_calling: false
      supports_reasoning: true

# ===========================================
# 复杂度路由 Hook
# ===========================================
litellm_settings:
  # 注册复杂度路由 Hook
  callbacks:
    - complexity_router.complexity_router_instance

  # 重试配置
  num_retries: 2
  request_timeout: 60

  # 故障转移配置
  fallbacks:
    # 本地模型失败 → 云端模型
    - "qwen-local": ["astron-code-latest"]
    # 云端推理失败 → 云端聊天模型 → 本地模型
    - "astron-code-latest": ["astron-code-latest", "qwen-local"]

  # 上下文窗口溢出时降级
  context_window_fallbacks:
    - "qwen-local": ["astron-code-latest"]
    - "astron-code-latest": ["astron-code-latest"]

  # 允许的连续失败次数
  allowed_fails: 3

  # 丢弃不支持的参数
  drop_params: true

# ===========================================
# 路由策略
# ===========================================
router_settings:
  # 由于我们使用自定义复杂度路由，这里设置为 simple-shuffle 作为 fallback
  routing_strategy: simple-shuffle
  timeout: 60

# ===========================================
# 服务配置
# ===========================================
general_settings:
  master_key: sk-openclaw-local
  port: 4000
  host: 0.0.0.0

五、环境变量配置

创建 ~/.openclaw/litellm/.env：

1
2

# 云端 API Keys
DEEPSEEK_API_KEY=sk-your-deepseek-key

五点五、配置 LiteLLM Proxy 的复杂度路由 Hook

在启动 LiteLLM Proxy 之前，确保 Hook 已正确配置：

1
2
3
4
5
6
7
8
9

# 1. 确保复杂度路由器文件存在
ls -la ~/.openclaw/litellm/complexity_router.py

# 2. 验证 config.yaml 中的 Hook 注册
grep -A 5 "callbacks" ~/.openclaw/litellm/config.yaml

# 3. 测试 Hook 导入
cd ~/.openclaw/litellm
python -c "from complexity_router import complexity_router_instance; print('Hook loaded successfully')"

六、启动与验证

6.1 启动 LiteLLM Proxy

1
2
3
4
5
6
7
8

cd ~/.openclaw/litellm

# 启动服务
litellm --config ~/.openclaw/litellm/config.yaml

# 或者后台运行
nohup litellm --config ~/.openclaw/litellm/config.yaml \
  --detailed_debug > litellm.log 2>&1 &

6.2 验证服务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 1. 检查健康状态
curl http://localhost:4000/health

# 2. 查看可用模型
curl http://localhost:4000/v1/model/list

# 3. 测试简单任务（应路由到本地模型）
curl -X POST http://localhost:4000/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-openclaw-local" \
  -d '{
    "model": "qwen-local",
    "messages": [{"role": "user", "content": "你好，请介绍一下自己"}]
  }'

# 4. 测试复杂任务（应路由到云端模型）
curl -X POST http://localhost:4000/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-openclaw-local" \
  -d '{
    "model": "astron-code-latest",
    "messages": [{"role": "user", "content": "深度分析人工智能对就业市场的影响，需要考虑技术进步、自动化、行业转型等多个维度"}]
  }'

6.3 查看日志验证路由

1
2
3
4
5
6

# 查看 LiteLLM 日志
tail -f ~/.openclaw/litellm/litellm.log | grep ComplexityRouter

# 预期输出示例：
# [ComplexityRouter] simple (score=-10) → qwen-local
# [ComplexityRouter] complex (score=3) → astron-code-latest

6.4 验证 OpenClaw 连接

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 测试 OpenClaw 与 LiteLLM Proxy 的连接
curl -X POST http://localhost:4000/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-openclaw-local" \
  -d '{
    "model": "qwen-local",
    "messages": [{"role": "user", "content": "测试连接"}]
  }'

# 验证复杂度路由是否生效
curl -X POST http://localhost:4000/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-openclaw-local" \
  -d '{
    "model": "astron-code-latest",
    "messages": [{"role": "user", "content": "深度分析人工智能发展趋势"}]
  }'

七、OpenClaw 配置

重要说明：OpenClaw 的配置只是连接到已配置好的 LiteLLM Proxy。复杂度路由完全在 LiteLLM 层实现，OpenClaw 本身不具备此功能。

编辑 ~/.openclaw/openclaw.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73