适用场景
ds4 是 Redis 作者发布的一个轻量级本地大模型推理工具，用 C 写成、依赖少、编译快，目标是让「在自己机器上跑一个能对话的模型」这件事尽量简单。这套方案适合：手上有一台内存够大的 Mac 或 Linux 工作站，希望数据完全不出本地、断网也能用、不想按 token 付费的开发者和运维同学。折腾完之后，你会得到一个能通过命令行和 HTTP 接口调用的离线 LLM 服务。
环境与前置条件
- 操作系统：macOS（Apple Silicon 体验较顺）或 Linux（x86_64 / arm64）。Windows 建议先装 WSL2，在里面的 Linux 环境操作。具体支持矩阵以官方仓库说明为准。
- 编译工具链：C 编译器（clang 或 gcc）、make、git、curl。这些都是系统包管理器一行命令能装上的东西。
- 内存：16 GB 起步，32 GB 会从容很多。4-bit 量化的权重粗略按「参数量 × 0.5~0.6 字节」估算，7B 级别模型大约占 5~6 GB，再叠加 KV cache。跑更大的模型，内存需求会明显上去。
- 磁盘：模型文件从几 GB 到上百 GB 不等，建议预留模型体积 2 倍以上的空间。
- 加速后端：没有 GPU 也能纯 CPU 跑，有 GPU 通常会快很多。具体支持哪些后端、如何开启，以官方文档当前版本为准。
- 网络：只在下载源码和模型时需要。装好之后，推理阶段完全可以拔网线。
分步骤部署
第 1 步：先摸清机器家底
动手之前花两分钟确认硬件，能省掉后面一半的坑。
```bash
uname -a # 系统和架构
sysctl -n hw.memsize # macOS 看内存（字节）
free -h # Linux 看内存
df -h . # 当前目录可用磁盘
```
成功标志：内存和磁盘数字心里有数，大致能判断自己该选多大的模型。
第 2 步：安装编译依赖
macOS：
```bash
xcode-select --install
brew install make git curl
```
Ubuntu / Debian：
```bash
sudo apt update
sudo apt install -y build-essential git curl
```
确认编译器就位：
```bash
cc --version
```
成功标志：能打印出编译器版本号，而不是 command not found。
第 3 步：获取源码并编译
从官方仓库拉源码（仓库地址以官方页面为准），然后编译：
```bash
git clone <ds4 官方仓库地址> ds4
cd ds4
make
```
这一步在做什么：把 C 源码编译成本机可执行文件。成功标志是当前目录下出现名为 ds4 的可执行文件，并且：
```bash
./ds4 --help
```
能打印出用法说明。如果 --help 只是刷出一堆参数，别跳过，从头读一遍——后面所有参数名都以这份输出为准。
第 4 步：准备并导入模型文件
ds4 读取的是量化后的模型权重文件，具体支持哪些格式，以官方文档当前版本为准（常见的是 GGUF 这类量化格式）。下载前先确认格式匹配，避免白下几十 GB。
```bash
mkdir -p models
把下载好的模型文件放进 models/ 目录
ls -lh models/
```
下载方式可以用 huggingface-cli、git lfs，或者直接 curl 拉取。下完做一次校验：
```bash
shasum -a 256 models/你的模型文件
```
如果模型发布页给了哈希值，比对一下。文件下载不完整，是后面「加载失败」最常见的原因，先查这里能省很多时间。
选模型的建议：先用 7B 级别的 4-bit 量化模型把全流程跑通，再换大模型。 第一次的目标是「跑起来」，不是「跑得大」。
第 5 步：单次推理自检
先别急着启动服务，用一次性推理确认链路是通的：
```bash
./ds4 --model ./models/你的模型文件 \
--prompt "用一句话解释什么是缓存" \
--ctx 2048 \
--threads 8
```
参数含义：
--ctx：上下文长度，也就是模型一次能「记住」多少 token。--threads：参与计算的线程数，一般设成物理核心数。
成功标志：终端流式打印出一段像样的中文回答，进程正常退出。到这一步，安装、模型导入、推理三件事就已经全通了。
第 6 步：启动常驻服务
```bash
./ds4 --model ./models/你的模型文件 \
--ctx 8192 \
--threads 8 \
--host 127.0.0.1 \
--port 8080
```
--host 127.0.0.1表示只允许本机访问，这是更安全的默认做法。- 想让局域网里的其他设备访问，改成
0.0.0.0，但务必配合防火墙和鉴权，不要把端口直接暴露到公网。
成功标志：日志里出现模型加载完成、KV cache 分配大小、监听端口等信息，进程保持前台运行不退出。
第 7 步：关键参数怎么调
| 参数 | 作用 | 起步建议 |
|---|---|---|
--ctx | 上下文长度 | 4096 或 8192，越大越吃内存，KV cache 随它线性增长 |
--threads | 计算线程数 | 物理核心数；超过之后收益变小甚至变慢 |
| temperature | 随机性 | 代码/问答 0.2~0.7，创意写作 0.8~1.0 |
| top-p / top-k | 采样范围 | 默认通常够用，想要更稳定的输出就调小 |
| max tokens | 单次生成长度上限 | 设一个上限，防止一次生成太多拖住服务 |
把常用参数固化进启动脚本，避免每次手敲：
```bash
cat > run.sh <<'EOF'
#!/usr/bin/env bash
./ds4 --model ./models/你的模型文件 --ctx 8192 --threads 8 --host 127.0.0.1 --port 8080
EOF
chmod +x run.sh
```
第 8 步：用 curl 调用接口
如果 ds4 提供 OpenAI 兼容接口，可以直接复用现有的客户端和脚本，省掉自己封装的工作量：
```bash
curl http://127.0.0.1:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"你好"}],"temperature":0.6,"stream":true}'
```
返回一段 JSON（开启 stream 时是逐块推送）就算成功。接口路径和字段名以官方文档当前版本为准；如果不是兼容接口，就照 README 里的示例格式来。
第 9 步：做一次性能基线测试
值得长期盯住的三个数字：首 token 延迟（TTFT）、生成速度（tokens/s）、内存占用。
```bash
time for i in $(seq 1 10); do
curl -s http://127.0.0.1:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"写一句关于缓存的话"}],"max_tokens":64}' > /dev/null
done
```
一边压测一边看资源占用：macOS 用 top -o mem，Linux 用 htop，有 N 卡可以另开一个终端跑 nvidia-smi。
调参要用「对照法」：固定同一个 prompt 和同一批参数，每次只改一个值（比如线程数 4 → 8 → 16），记录 tokens/s，找出本机的拐点。改一堆参数一起看，等于什么都没测。
验证部署是否成功
按顺序过一遍，五条全中才算真的搭好了：
1. ./ds4 --help 有用法输出 → 二进制可用。
2. 第 5 步的一次性推理能打印回答 → 模型加载与推理正常。
3. 第 6 步启动后日志显示监听端口 → 服务正常。
4. 第 8 步 curl 能拿到 JSON 结果 → 接口正常。
5. 断开网络，重复第 4 步，依然成功 → 确认是真正的离线环境。
第 5 条容易被忽略，但它才是「本地离线」这四个字的意义所在。
常见报错与解决
1. error: model file not found 或 failed to open model
原因：路径写错、模型文件没下完，或者格式不被当前版本支持。
```bash
ls -lh models/ # 确认文件存在且体积正常
shasum -a 256 models/你的模型文件 # 与发布页哈希对比
```
确认无误后，再用官方 README 点名支持的格式重新下载。
2. unknown model architecture 或 unsupported model format
原因：模型格式或量化类型与 ds4 当前版本不匹配。这类工具迭代较快，格式支持会变。
解决：对照官方文档当前版本，换成明确支持的格式重新下载，不要凭文件名猜。
3. 进程被系统 Killed，或内存瞬间打满
原因：上下文长度或模型规模超出可用内存。
```bash
./ds4 --model ./models/你的模型文件 --ctx 2048 --threads 8
```
先把 --ctx 降下来，换更小或量化程度更高的模型，同时关掉浏览器等占内存的程序。
4. make: * No targets specified and no makefile found 或编译报缺头文件**
原因：源码没下完整（子模块没拉），或依赖没装齐。
```bash
git submodule update --init --recursive # 仓库若使用子模块
make clean && make
```
仍然失败就回 README 逐条核对依赖清单。
5. Address already in use
原因：端口被别的进程占着。
```bash
lsof -i :8080 # 找出占用进程
./ds4 ... --port 8081 # 或者直接换端口
```
6. 回答出现乱码、复读或异常截断
原因：上下文被塞满、采样参数不合适、或者 prompt 模板和模型不匹配。
解决：检查对话模板是否与模型对应，适当降低 temperature，必要时提高 --ctx。
后续维护
- 备份：模型文件丢了可以重新下，启动脚本和参数配置丢了才麻烦。把
run.sh、参数说明、模型格式备注整理成一个notes.md，放进 git 仓库管理。 - 升级：
git pull前先看变更说明。升级后重跑第 9 步的性能基线，和旧数据对比，避免「新版变慢」而毫无察觉。模型格式可能随版本变化，建议保留旧二进制以便回滚。 - 日志：把输出重定向到文件，方便事后排查。
```bash
./run.sh >> ds4.log 2>&1 &
tail -f ds4.log
```
长期跑建议交给 systemd（Linux）或 launchd（macOS）托管，并配置日志轮转，别让日志把磁盘吃满。
- 监控：重点看内存占用、连续运行几小时后的响应速度是否衰减（排查内存泄漏）、以及磁盘剩余空间。任何一项异常，都值得记录下来。
- 安全：默认只监听
127.0.0.1。确实需要对外提供服务时，前面加一层反向代理和鉴权，不要图省事直接把端口暴露出去。 - 复用：把跑通的环境固化成脚本之后，换模型只需要改
--model一行，测试新模型、对比效果都会轻松很多。