There are many places a frontier model can run. This one you can inspect, fork and repair. 最先進的模型可以跑在很多地方。
這一個，你可以檢視、分叉、修復。

v 0.8: a second engine, with earlier releases kept for the recordv 0.8：多一個引擎，舊版紀錄留在後面

Version 0.8.0 renames the extension to pi-kami and adds a second engine. Choose rec/flint in pi and pi-kami runs Flint, Recursive’s open-weight model, on Recursive’s own engine rec, pinned at 0.1.0. ds4/deepseek-v4-flash is still the DeepSeek tier, with the Maya-XS weights from 0.7.3. The runtime names stay as they were: ~/.pi/ds4/ and every DS4_* variable keeps its spelling.

0.8.0 把擴充套件改名為 pi-kami，並多了一個引擎。在 pi 裡選 rec/flint，pi-kami 會用 Recursive 自家的引擎 rec（固定在 0.1.0）來跑 Recursive 的開放權重模型 Flint。ds4/deepseek-v4-flash 仍是 DeepSeek 這一層，沿用 0.7.3 的 Maya-XS 權重。執行期的名稱都沒變：~/.pi/ds4/ 和所有 DS4_* 變數照舊。

0.8.0What changed in the extension擴充套件改了什麼

• A new name. pi-ds4 is now pi-kami: pi install https://github.com/audreyt/pi-kami. The old URL still works through GitHub’s redirect. Install from one of them only. pi sees two packages, and the second copy stays inactive and shows a warning.
• Flint through rec, experimental. For an M4 Pro, M5 Pro or M5 Max with 48 GB or more. The first use installs rec 0.1.0, downloads about 23 GB and starts rec serve on 127.0.0.1:11500. Details in §1.1a.
• Replay still works. Flint gets seed 42 by default too. rec 0.1.0 gives tool calls random IDs, so Flint traces differ in those IDs and nowhere else.
• What Flint leaves out. Flint has no vision, no directional steering, no ds4-agent and no Anthropic protocol. Those features stay with the ds4 tier.
• Unchanged. Linux CUDA and ROCm hosts and the other Macs under 128 GB still have no managed model. The v 0.6.1 advice for them stands.

• 新名字。pi-ds4 改名為 pi-kami：pi install https://github.com/audreyt/pi-kami。舊網址透過 GitHub 轉址仍然可用。兩個網址只能擇一安裝，否則 pi 會把它們當成兩個套件，第二份不會啟用，還會跳出警告。
• Flint 搭 rec（實驗性質）。適用於 48 GB 以上的 M4 Pro、M5 Pro 或 M5 Max。第一次使用時會安裝 rec 0.1.0、下載約 23 GB，並在 127.0.0.1:11500 啟動 rec serve。細節見 §1.1a。
• 重播照樣成立。Flint 預設也送種子 42。rec 0.1.0 給工具呼叫的 ID 是隨機的，所以 Flint 的兩份軌跡只差在這些 ID。
• Flint 少了什麼。Flint 沒有視覺、方向性引導、ds4-agent，也不支援 Anthropic 協定。這些功能都留在 ds4 這一層。
• 沒變的。Linux CUDA、ROCm 主機，以及其他不到 128 GB 的 Mac，仍然沒有代管模型，照舊參考 v 0.6.1 的建議。

Why bring a model home為什麼把模型帶回家

Everything here starts from one question, the one behind Software Freedom as Civic Care: when an AI system fails, can the people who inherit it still repair it? Not the vendor. Not the people who trained it. The people left holding it on the day it stops behaving: a newsroom, a research group, a town office, a family.

這一切都從一個問題開始，也就是〈軟體自由與公民關懷〉背後的那個問題：AI 系統壞掉的時候，接手它的人還修得動嗎？不是廠商，也不是訓練它的人，而是最後把它抱在手上的人。可能是一間編輯室、一個研究團隊、一處鄉公所，或一個家庭。它開始不聽話的那一天，要修它的就是他們。

Running a frontier model on your own Mac is only the visible part of the answer. A local model you can’t inspect, can’t fork and can’t roll back is just a cloud service that happens to sit on your desk. It becomes civic infrastructure only when four things are readable at once: the model itself, the settings that shape it, the memory it carries between turns and the steps you would take to repair it. Then AI can join the loops of care that already exist, in families, in projects and in democratic communities. It won’t pull people into a platform’s own loop.

在自己的 Mac 上跑最前沿的模型，只是答案看得見的那一半。如果模型你看不進去、不能分叉、也退不回舊版，它就只是剛好放在你桌上的雲端服務。要成為公民基礎建設，四樣東西得同時看得懂：模型本身、塑造它的設定、它在每一輪對話之間帶著的記憶，還有壞了該怎麼修的步驟。做到這樣，AI 才能加入原本就有的照護循環，像是家庭裡的、專案裡的、民主社群裡的，而不是把人拉進平台自己的循環。

That’s why this fork makes the choices it makes, and every one of them costs something. The server runs a single stream with a fixed seed. That gives up the speed of batching, so that a trace can be replayed. The engine and the weights are pinned to a commit. That gives up “latest”, so that next year’s install is the one tested this year. Steering changes how the model answers, not what it believes. That gives up the satisfaction of forcing a conclusion, so that a closed question can be reopened as a discussion. And all the running state (the lock, the leases, the server’s PID and arguments, the log) lives as plain files under ~/.pi/ds4/. On a bad day you read files, not source code.

所以這個分叉做了這些選擇，而每一個選擇都有代價。伺服器只開一條串流，還帶固定的種子（seed）。代價是放棄批次處理的速度，換來一段可以重跑的過程。引擎和權重都釘在特定的 commit 上。代價是放棄「最新版」，換來明年裝的，就是今年測過的那一版。引導只改變模型怎麼回答，不改變它相信什麼。代價是放棄硬逼出結論的痛快，換來一個被封死的問題，可以重新變成討論。另外，執行中的所有狀態，包括鎖、租約、伺服器的 PID 與參數、log，都是放在 ~/.pi/ds4/ 底下的純文字檔。出狀況的那天，你讀檔案就好，不用讀原始碼。

The engine matters for the same reason. antirez wrote ds4 in plain C, in the tradition of Redis: one source tree, one Makefile, no Python environment to rot and a GGUF file (the model’s weight file) that the engine reads directly, with no conversion step. mitsuhiko’s pi-ds4 wrapped that engine in code that manages starting, running and stopping the server: leases, a watchdog and a lock. It’s small enough to read in an afternoon. This fork keeps all of it and adds a civic layer on top: reproducibility, pinned downloads, the vision sidecar and a steering option you can decline.

引擎也是同樣的道理。antirez 用純 C 寫了 ds4，延續他寫 Redis 的作風：一棵原始碼樹、一份 Makefile、沒有會慢慢壞掉的 Python 環境。引擎直接讀 GGUF（模型的權重檔），中間不必轉檔。mitsuhiko 的 pi-ds4 替這個引擎加了一層管理啟動與關閉的機制：租約、看門狗（watchdog）和鎖。它小到一個下午就讀得完。這個分叉全部保留，再疊上公民這一層：可重現、固定版本的下載、視覺附屬檔，以及一個你可以拒絕的引導選項。

Local inference doesn’t just save you the API fee. It hands the steering wheel back.在本機跑模型，省下的不只是 API 費用，還把方向盤還給你。

The full argument, with its ethical and political context, is in the further reading at the end of this letter.

完整的論述，包括它的倫理與政治背景，收在信末的延伸閱讀。

Who this letter is for這封信寫給誰

The opening answered “what is this, and is it for me?”. What follows is for readers who have decided to set every knob themselves: the full operating manual for the audreyt fork. It isn’t a translation of the README and it isn’t marketing. Where a default looks odd, the reason is written next to it.

開場回答了「這是什麼？適合我嗎？」接下來寫給想自己調好每一個旋鈕的讀者，是 audreyt 分叉的完整操作手冊。它不是 README 的翻譯，也不是宣傳文案。哪個預設值看起來奇怪，理由就寫在旁邊。

• Chapter 0: why this exists, in the language of civic care.
• Chapters 1 and 2: the hardware you need, the one-line install, and what actually happens on first launch.
• Chapters 3 and 4: the model, with abliteration (a treatment that makes it refuse less) and the Maya-XS profile, then the fork’s signature feature, directional steering.
• Chapters 5 and 6: every environment variable, then tuning the context window (how much text the model can hold in view at once) and the KV cache (its short-term memory).
• Chapter 7: day-to-day use, from the API and the log to leases and the native agent.
• Chapter 8: pi-kami as a backend for Codex CLI, Claude Code, OpenClaw and Hermes Agent, including the path for non-Mac hardware.
• Chapters 9 to 11: troubleshooting, the local development install, and building your own steering direction.

• 第零章：它為什麼存在，從公民關懷的角度說。
• 第一、二章：需要的硬體、一行安裝，以及第一次啟動時到底發生什麼事。
• 第三、四章：這顆模型（Maya-XS 版本，以及 abliteration 這種去除拒答傾向的處理），還有這個分叉的招牌功能：方向性引導。
• 第五、六章：每一個環境變數，然後是 context（模型一次能讀的文字長度）與 KV cache（模型的短期記憶）的調校。
• 第七章：日常使用，包括 API、log、租約和原生智慧體。
• 第八章：把 pi-kami 當成 Codex CLI、Claude Code、OpenClaw、Hermes Agent 的後端，也包括非 Mac 硬體的做法。
• 第九到十一章：故障排除、本機開發安裝、自己建一個引導方向。

Read it start to finish as one full install, or jump to a chapter when you need a value. Both are intended.

可以從頭讀到尾，當成一次完整的安裝，也可以在需要某個數值時，直接翻到那一章。兩種讀法都行。

The hardware bar and the one-line install硬體門檻與一行安裝

Check your machine before you type the command. That isn’t gatekeeping. A model that almost fits is the worst case. DeepSeek V4.1 Flash is a Mixture-of-Experts model (many specialist sub-networks, only a few used at a time) with 40 layers and 384 routed experts. The Maya-XS takes about 341.5 GiB on disk including the vision sidecar, and about 107.35 GiB of weights stay resident in memory. The two Engram tables, about 189 GiB, stay on disk. That’s why a 128 GB machine can hold it at all, and why nothing smaller can. Running it still needs unified memory (the memory the CPU and GPU share) for activations (the model’s internal signals) and the KV cache, and macOS will freeze before it complains.

輸入指令之前，先看看你的機器。這不是在設門檻，而是因為「差一點就裝得下」的模型，是最糟的情況。DeepSeek V4.1 Flash 是 Mixture-of-Experts（專家混合）模型，有 40 層、384 個路由專家，每次只動用其中幾個。Maya-XS 版連同視覺附屬檔，在硬碟上約 341.5 GiB，其中約 107.35 GiB 的權重會常駐記憶體，兩張 Engram 表（約 189 GiB）則留在硬碟上。所以 128 GB 的機器才裝得下，再小的就不行。執行時還需要統一記憶體（CPU 與 GPU 共用的記憶體），用來放激勵值（模型內部的訊號）和 KV cache。而 macOS 不會先抱怨，它會直接卡死。

1.1Minimum hardware最低硬體需求

• Memory: 128 GB, on Apple Silicon. The ds4 tier refuses a Mac with less memory at the start. ds4 keeps a 112 GiB memory budget for V4.1, and about 107.35 GiB of weights stay resident. An M4 Pro, M5 Pro or M5 Max with 48 GB or more can choose rec/flint instead (§1.1a). Other Macs under 128 GB should stay on v 0.6.1, which runs the V4 Vision-Exp IQ2 build on 96 GB.
• Wired-memory ceiling. macOS lets Metal lock down only about 107.5 GiB of a 128 GB Mac by default, less than the Maya-XS and its vision sidecar need under ds4’s 112 GiB budget. Raise the ceiling once with sudo sysctl iogpu.wired_limit_mb=114688, which matches that budget, and add iogpu.wired_limit_mb=114688 to /etc/sysctl.conf to keep it across reboots. The extension checks this before it downloads the model and prints the command if it is missing.
• Disk. The language file and the vision sidecar together take 366 684 242 080 bytes (about 341.5 GiB, or 366.7 GB). Add the KV disk cache, 64 GB by default on a 128 GB Mac when DS4_KV_DISK_SPACE_MB is unset, then the ds4 source tree, the build and the logs. For a fresh install, plan on about 367 GB plus the KV cache. An upgrade from v 0.6.x keeps the old 81.63 GiB pair until the new one passes its size checks, so it peaks near 455 GB. download_model.sh checks free space before it starts. An internal SSD matters, as the two Engram tables (about 189 GiB) stay on disk.
• Chip. Apple Silicon, Metal only. Linux hosts with CUDA or ROCm are refused before anything downloads, as ds4 runs the IQ1_S experts only on Metal. They can stay on v 0.6.1, or bring their own GGUF and binary through DS4_RUNTIME_DIR (§8.7).
• Energy Mode. Set Energy Mode to High Power while the model runs (System Settings › Battery › Energy Mode on a MacBook). High Power generates about 37.2 t/s. On earlier builds of this engine, Low Power decoded at less than half the High Power rate.
• Network. The first download is 341.5 GiB, so expect many hours on a typical home connection. It is resumable with curl -C -. If your Hugging Face account gets you faster downloads, set HF_TOKEN.

• 記憶體：128 GB，而且要是 Apple Silicon。記憶體比這少的 Mac，ds4 這一層會在啟動時拒絕。ds4 對 V4.1 的記憶體預算是 112 GiB，約 107.35 GiB 的權重會常駐記憶體。48 GB 以上的 M4 Pro、M5 Pro 或 M5 Max，可以改選 rec/flint（§1.1a）。其他不到 128 GB 的 Mac 請留在 v 0.6.1，它在 96 GB 上跑 V4 Vision-Exp IQ2 版。
• 可鎖定記憶體上限。macOS 預設只讓 Metal 鎖住 128 GB Mac 裡約 107.5 GiB 的記憶體，比 Maya-XS 加視覺附屬檔在 ds4 的 112 GiB 預算下需要的少。請先執行一次 sudo sysctl iogpu.wired_limit_mb=114688（剛好對應這個預算）調高上限。如果希望這個設定在重新開機後仍然有效，就把 iogpu.wired_limit_mb=114688 加進 /etc/sysctl.conf。擴充套件在下載模型之前會先檢查，沒設定時會印出這行指令。
• 硬碟。語言檔加視覺附屬檔，合計 366 684 242 080 位元組（約 341.5 GiB，也就是 366.7 GB）。再加上 KV 磁碟快取：沒設 DS4_KV_DISK_SPACE_MB 的話，128 GB 的 Mac 預設 64 GB。還要加 ds4 原始碼、編譯產物和 log 的空間。全新安裝請預留約 367 GB，外加 KV 快取。從 v 0.6.x 升級時，舊的 81.63 GiB 一對檔案會先留著，等新的一對通過大小檢查後才刪，所以用量最高約 455 GB。download_model.sh 開始前會先檢查剩餘空間。內建 SSD 很重要，因為兩張 Engram 表（約 189 GiB）留在硬碟上。
• 晶片。Apple Silicon，只走 Metal。裝有 CUDA 或 ROCm 的 Linux 主機，會在下載之前就被拒絕，因為 ds4 只在 Metal 上執行 IQ1_S 專家。這些主機可以繼續用 v 0.6.1，或用 DS4_RUNTIME_DIR 自備 GGUF 與執行檔（§8.7）。
• 能源模式。模型執行時，請把能源模式設成「高功率」（MacBook 在「系統設定 › 電池 › 能源模式」）。高功率的生成約 37.2 t/s。在這個引擎較早的版本上，低耗電模式的 decode 不到高功率時的一半。
• 網路。第一次要下載 341.5 GiB，一般家用網路要好幾個小時，而且可以用 curl -C - 續傳。如果你的 Hugging Face 帳號可以加速下載，就設定 HF_TOKEN。

1.1aFlint through rec: the 48 to 96 GB routeFlint 搭 rec：48 到 96 GB 的選項

Version 0.8 adds an engine for the Macs the ds4 tier turns away. rec 0.1.0 supports only the M4 Pro, M5 Pro and M5 Max, so this route is for those chips with 48 to 96 GB of unified memory. A 128 GB Mac can use it too. Pick rec/flint as the model in pi. ds4/deepseek-v4-flash stays the DeepSeek tier.

0.8 版為被 ds4 層擋下的 Mac 多加了一個引擎。rec 0.1.0 只支援 M4 Pro、M5 Pro 和 M5 Max，所以這個選項是給搭載這幾款晶片、統一記憶體 48 到 96 GB 的 Mac。128 GB 的 Mac 也能用。在 pi 裡把模型選成 rec/flint 即可，ds4/deepseek-v4-flash 仍是 DeepSeek 那一層。

Flint is Recursive’s open-weight model (Apache 2.0). It is a 40B-parameter Mixture-of-Experts that uses 2.5B parameters per token and takes about 23 GB at 4-bit. It reads text only and is not abliterated. rec is Recursive’s engine (also Apache 2.0), and pi-kami pins it at 0.1.0. Recursive reports more than 125 tokens/s on an M4 Pro. This guide has not measured Flint’s speed, so treat that figure as Recursive’s.

Flint 是 Recursive 的開放權重模型（Apache 2.0），400 億參數的 Mixture-of-Experts，每個 token 只動用 25 億，4-bit 約 23 GB。它只讀文字，也沒有經過 abliteration。rec 是 Recursive 的引擎（同樣是 Apache 2.0），pi-kami 把它固定在 0.1.0。Recursive 說 M4 Pro 上每秒超過 125 個 token。本信沒有自己量過，這個數字請當作 Recursive 的說法。

The first time you use it, pi-kami does three things:

第一次使用時，pi-kami 會做三件事：

• It installs rec 0.1.0 with Recursive’s installer. The installer adds ~/.local/bin to PATH in your shell profile.
• It downloads about 23 GB.
• It starts rec serve on 127.0.0.1:11500, or reuses a rec server that is already running. When the last pi-kami window quits, it stops the server only if pi-kami started it.

• 用 Recursive 的安裝程式裝好 rec 0.1.0。安裝程式會在你的 shell 設定檔裡把 ~/.local/bin 加進 PATH。
• 下載約 23 GB。
• 在 127.0.0.1:11500 啟動 rec serve，若已有 rec 伺服器在跑就直接沿用。最後一個 pi-kami 視窗關掉時，只有 pi-kami 自己啟動的伺服器才會被停掉。

Replay and pinning carry over. pi-kami sends seed 42 by default, and the same DS4_REPRODUCIBLE and DS4_REPRODUCIBLE_SEED settings apply. Two identical runs through stock pi 1.3.0 gave byte-identical output, and a different seed gave different output. One gap remains. rec 0.1.0 still assigns random IDs to tool calls, so two traces differ in those IDs and nowhere else. A fix is waiting upstream as recursive-oss/rec pull request #3.

重播與釘版都沿用。pi-kami 預設送種子 42，DS4_REPRODUCIBLE 和 DS4_REPRODUCIBLE_SEED 照樣有效。用原版 pi 1.3.0 跑兩次相同輸入，輸出逐位元組相同，換一個種子，輸出就不同。還有一個缺口：rec 0.1.0 給工具呼叫的 ID 仍是隨機的，所以兩份軌跡只差在這些 ID。修正已提交上游，是 recursive-oss/rec 的 pull request #3。

Flint has no image input, no directional steering, no ds4-agent and no Anthropic protocol. Chapter 4 and the vision sidecar details in Chapter 3 apply only to the ds4 tier.

Flint 沒有圖片輸入、方向性引導、ds4-agent，也不支援 Anthropic 協定。第四章，以及第三章關於視覺附屬檔的部分，都只適用於 ds4 那一層。

1.2If you installed the upstream extension before如果你之前裝過上游版本

This extension and mitsuhiko/pi-ds4 register the same provider and model ID, ds4/deepseek-v4-flash, so they can’t live side by side. Remove the upstream one first:

本擴充套件和 mitsuhiko/pi-ds4 註冊的 provider 與模型 ID 完全一樣，都是 ds4/deepseek-v4-flash，所以不能同時存在。請先移除上游版本：

# 只有裝過 mitsuhiko/pi-ds4 才需要這一步only needed if mitsuhiko/pi-ds4 was ever installed
pi remove github.com/mitsuhiko/pi-ds4

1.3The one line: check that pi is there first那一行安裝指令：先確認 pi 在不在

This extension sits on top of earendil-works/pi. The install line assumes pi is already on your machine, so take five seconds to check:

本擴充套件建立在 earendil-works/pi 之上。安裝指令假設你的機器上已經有 pi，所以先花五秒確認一下：

# 應該印出版本號。若是 command not found，先依 github.com/earendil-works/pi 的說明裝好 pi 再回來。should print a version. If it says command not found, install pi per github.com/earendil-works/pi and come back.
pi --version

pi install https://github.com/audreyt/pi-kami

This used to be pi-ds4. The old URL, https://github.com/audreyt/pi-ds4, works through GitHub’s redirect, but install from only one of them. pi treats the two URLs as separate packages, and the second copy stays inactive and shows a warning.

前身是 pi-ds4。舊網址 https://github.com/audreyt/pi-ds4 透過 GitHub 轉址仍然可用，但請只用其中一個安裝。pi 會把兩個網址當成兩個套件，第二份不會啟用，還會跳出警告。

That’s the whole command. Cloning the engine source, building ds4-server, downloading the 366.7 GB language-and-sidecar pair, starting the server and registering the provider all happen in the background. Everything is logged.

指令就這一行。把引擎原始碼 clone 下來、編譯 ds4-server、下載 366.7 GB 的語言檔與視覺附屬檔、啟動伺服器、註冊 provider，全都在背景完成，而且每一步都有 log 紀錄。

What happens on first launch第一次啟動會發生什麼事

The install command only registers the extension. Nothing heavy happens until you first select ds4/deepseek-v4-flash. A 341.5 GiB download should be something you asked for, not something that happened while you were installing a package. Every step is written to ~/.pi/ds4/log.

安裝指令只是先登記一下，還沒有開始做事。要等你第一次真的選用 ds4/deepseek-v4-flash，才會動手。因為 341.5 GiB 的下載，應該是你自己開口要的，不該在你裝套件時悄悄發生。每一步都會記在 ~/.pi/ds4/log。

2.1The startup sequence啟動的六個步驟

When any pi process first sends a request to the model, the extension runs these six steps in order:

任何一個 pi 程序第一次向這個模型發出請求時，擴充套件會依序做這六件事：

1. 1

   Take the cross-process startup lock拿到啟動鎖（各程序共用）

   The extension writes who holds the lock to ~/.pi/ds4/lock/owner.json. That way two pi windows can't run the same setup at once.

   擴充套件把「誰拿著鎖」寫進 ~/.pi/ds4/lock/owner.json。這樣兩個 pi 視窗就不會同時做同一份準備工作。

2. 2

   Find the runtime directory找到執行用的資料夾

   If ~/.pi/ds4/support/ is missing, or doesn't look like a ds4 checkout (a downloaded copy of the source), the extension makes a shallow clone, a copy without the full history:

   如果 ~/.pi/ds4/support/ 不存在，或看起來不像 ds4 的原始碼副本（checkout），就做一次淺層 clone，也就是只抓最新的內容，不抓完整的歷史：

   # 預設來自 DS4_SUPPORT_REPO 與 DS4_SUPPORT_BRANCHdefaults from DS4_SUPPORT_REPO and DS4_SUPPORT_BRANCH git clone --depth 1 --single-branch \ --branch main \ https://github.com/audreyt/ds4 \ ~/.pi/ds4/support
3. 3

   Build ds4-server編譯 ds4-server

   If the ds4-server program doesn't exist yet, make ds4-server builds it inside the support directory.

   如果還沒有 ds4-server 這支程式，就在 support 資料夾裡執行 make ds4-server 把它編出來。

4. 4

   Make sure the model is there確認模型已經在硬碟上

   The bundled download_model.sh maya-xs (aliases q1 and preferred) first checks your free disk space. The language file has to pass size and SHA-256 checks before it goes live:

   內附的 download_model.sh maya-xs（別名 q1 和 preferred）會先檢查剩餘的硬碟空間。語言檔要通過大小和 SHA-256 檢查，才會啟用：

   ( set -e # curl -C - 可以續傳。兩個檔案都驗證過，才切換 ds4flash。語言檔先核對雜湊，再改名。curl -C - resumes. ds4flash switches only after both files verify, and the language file’s hash is checked before the rename. curl -fL --progress-meter -C - \ -o gguf/DeepSeek-V4.1-Flash-1017-Maya-XS-Abliterated.gguf.part \ https://huggingface.co/audreyt/DeepSeek-V4.1-Flash-Abliterated-GGUF/resolve/89cba799fcddca88bde8c8cfa8006d28dbf8dc79/DeepSeek-V4.1-Flash-1017-Maya-XS-Abliterated.gguf printf '%s %s\n' \ f414995b3797f77009634fac995f50834e70393771f9423fca984c892503b42a \ gguf/DeepSeek-V4.1-Flash-1017-Maya-XS-Abliterated.gguf.part | shasum -a 256 -c - mv gguf/DeepSeek-V4.1-Flash-1017-Maya-XS-Abliterated.gguf.part gguf/DeepSeek-V4.1-Flash-1017-Maya-XS-Abliterated.gguf curl -fL --progress-meter -C - \ -o gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf.part \ https://huggingface.co/audreyt/deepseek-v4.1-flash-1017-gguf/resolve/5ab6e05050613bf0dfcfb48426d3aaa4cb422cd0/DeepSeek-V4.1-Flash-1017-Vision.gguf mv gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf.part gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf ln -sfn gguf/DeepSeek-V4.1-Flash-1017-Maya-XS-Abliterated.gguf ds4flash.gguf )
5. 5

   Launch ds4-server啟動 ds4-server

   The server starts in the background on 127.0.0.1:8000 with the built-in arguments. It gets nothing you didn't ask for:

   伺服器在背景啟動，位址是 127.0.0.1:8000，用的是內建的參數。你沒要求的東西，一樣都不會加：

   ds4-server \ --ctx 128000 \ --kv-disk-dir ~/.pi/ds4/kv \ --kv-disk-space-mb 65536 \ --vision gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf # 65536 is the default on a 128 GB Mac # steering is off unless you opt in with your own V4.1 direction (Chapter 4): # --dir-steering-file <your 40 × 5120 direction file> # --dir-steering-ffn <strength> --dir-steering-attn 0
6. 6

   Start the watchdog啟動看門狗

   The extension starts /bin/sh ds4-watchdog.sh in the background. Every two seconds it looks through clients/. When no valid lease is left, it sends SIGTERM (a polite "please stop" signal) to the server and quits. This is how the memory comes back when you walk away.

   擴充套件會在背景啟動 /bin/sh ds4-watchdog.sh。它每兩秒檢查一次 clients/。要是沒有任何有效的租約，就對伺服器送出 SIGTERM（請它結束的訊號），然後自己也收工。你一離開，記憶體就是這樣還回來的。

You can safely run the whole sequence again. The second time, everything is already in place, so it starts at step 5. If the server is already running, it skips step 5 too.

整個流程可以放心重跑。第二次啟動時，東西都已就緒，所以直接從第五步開始。如果伺服器還在跑，連第五步都省了。

Your first use might be /ds4-agent instead of the model picker. Steps 1 to 4 stay the same. Step 3 builds ds4-agent instead. Then the HTTP server and watchdog are skipped, and the terminal goes straight to the native agent. Details are in §7.5.

如果你第一次用的是 /ds4-agent，而不是模型選單，前四步都一樣。第三步改成編譯 ds4-agent。接著會跳過 HTTP 伺服器和看門狗，直接把終端機交給原生的智慧體。細節請看 §7.5。

2.2Seeing where it is right now看看現在進行到哪了

Inside pi, /ds4 opens a live log window. While the 341.5 GiB pair of files downloads, you'll see curl's progress meter squeezed into one line: percentage, speed and time left.

在 pi 裡輸入 /ds4，會開啟即時的 log 視窗。那一對 341.5 GiB 的檔案在下載時，你會看到 curl 的進度條被縮成一行：百分比、速度、剩下的時間。

The model: DeepSeek V4.1 Flash, the Maya-XS build and the vision sidecar這顆模型：DeepSeek V4.1 Flash、Maya-XS 版本與視覺附屬檔

Take five minutes to learn what you’re running. A quantised (shrunk to fit), abliterated (made to refuse less) model is a bundle of trade-offs someone else made for you. This chapter lays them out so you can check them, or turn them down. The extension downloads DeepSeek V4.1 Flash 1017 Maya-XS abliterated from audreyt/DeepSeek-V4.1-Flash-Abliterated-GGUF, together with a vision sidecar (DeepSeek-V4.1-Flash-1017-Vision.gguf). It is not the V4 Vision-Exp IQ2 of v 0.6, and §3.3 says plainly what that trade costs.

花五分鐘，弄清楚你在跑的是什麼。這顆模型經過量化（壓小，好塞進記憶體）和 abliteration（讓它少拒絕一些），裡面是別人替你做的一堆取捨。這一章把它們全攤開，讓你檢查，也可以不接受。擴充套件下載的是 audreyt/DeepSeek-V4.1-Flash-Abliterated-GGUF 的 DeepSeek V4.1 Flash 1017 Maya-XS abliterated，加上一個視覺附屬檔（DeepSeek-V4.1-Flash-1017-Vision.gguf）。它不是 v 0.6 的 V4 Vision-Exp IQ2，這筆取捨的代價，§3.3 會老實說明。

3.1What DeepSeek V4.1 Flash isDeepSeek V4.1 Flash 是什麼

It is a Mixture-of-Experts (MoE) model with 40 layers, 384 routed experts plus one shared expert and 6 routed experts used for each token. MoE means only a few specialist parts switch on for each piece of text. A token is the smallest chunk of text the model reads and writes. The hidden width, the size of the vector that carries each token through the layers, is 5120. The official context window, how much text the model can keep in view at once, is 1M tokens. This extension opens 128k by default to leave room for the vision sidecar, and a 128 GB Mac cannot open the full 1M (§6.4).

它是一顆有 40 層的 Mixture-of-Experts（MoE，專家混合）模型，有 384 個路由專家加上一個共用專家，每個 token 用其中 6 個路由專家。意思是每處理一小段文字，只會啟動幾個專家。token 是模型讀寫文字的最小單位。隱藏層寬度（帶著每個 token 穿過各層的向量大小）是 5120，官方的 context window（一次能放在眼前的文字量）是 1M 個 token。這個擴充套件預設開 128k，好替視覺附屬檔留空間。128 GB 的 Mac 開不了完整的 1M（§6.4）。

The engine is antirez’s ds4. It’s a local inference engine, meaning the program that runs the model on your own machine. It is written in plain C in the Redis tradition. This extension uses the main branch of the audreyt/ds4 fork, pinned at 0dff39f. That build loads the embedding, compressor and indexer in Q8 through execution paths ds4 already had. It also has IQ1_S on Metal, a faster single-token Q5_K/Q6_K route, the V4.1 context fit, kernelpool’s V4.1 Metal work and one bundled V4.1 steering direction. The managed launch leaves directional steering off (Chapter 4).

引擎是 antirez 的 ds4。它是本機推論引擎，也就是在你自己的電腦上讓模型跑起來的程式，用純 C 寫成，延續 Redis 的風格。這個擴充套件用的是 audreyt/ds4 分叉的 main 分支，固定在 0dff39f。這個版本沿用 ds4 原有的執行路徑，以 Q8 載入 embedding、compressor 和 indexer，也包含 Metal 上的 IQ1_S、更快的單 token Q5_K／Q6_K 路徑、V4.1 的 context 適配、kernelpool 的 V4.1 Metal 工作，以及一個附帶的 V4.1 引導方向。代管啟動時，方向性引導預設關閉（第四章）。

V4.1 adds two Engram lookup tables, about 189 GiB together, from which the model reads only a few rows per token. ds4 leaves them on disk. The other weights, about 107.35 GiB, stay resident in memory on Metal. That is why an internal SSD matters, and why a 128 GB Mac is the floor.

V4.1 多了兩張 Engram 查找表，合計約 189 GiB，模型每個 token 只讀其中幾列。ds4 把它們留在硬碟上，其餘約 107.35 GiB 的權重常駐在 Metal 的記憶體裡。這就是內建 SSD 很重要的原因，也是 128 GB 的 Mac 成為門檻的原因。

3.2What abliteration is, and what it is notabliteration 是什麼，不是什麼

The abliterated V4.1 GGUF has had a small operation. Abliteration edits the model's internal signals (its activations) with a low-rank change, meaning a very small, targeted one. First, find the one internal direction that lights up when the model meets prompts it was trained to refuse. A prompt is just the text you give the model. Then remove that direction while the model computes its answer. The trained "I cannot respond to that" reply gets pried open, and a more natural continuation takes its place.

這份 abliterated V4.1 GGUF 動過一個小手術。abliteration 是對模型內部的訊號（激勵值）做低秩編輯，也就是範圍很小、很有針對性的改動。做法是：先找出一個方向，當模型遇到它被訓練成要拒絕的提示（prompt，就是你丟給模型的那段文字）時，這個方向就會亮起來。然後在模型算答案的過程中，把這個方向拿掉。訓練出來的那句「我無法回應這個請求」就被撬開了，換成比較自然的接續。

What it loosens is the over-refusal layer. It doesn't touch the model's judgement about content. That judgement still comes from whatever the model learned in training. In this build, the edit lives in 38 attn_output_b tensors from pqhaz’s Heretic edit of the 1017 checkpoint (pqhaz/DeepSeek-V4.1-Flash-1017-heretic), which removes the refusal direction from the attention output projection in blocks 2 to 39. pqhaz reports held-out refusals falling from 92 in 100 to 1 in 100, a KL divergence of 0.136 on harmless prompts (how far ordinary answers drift from the original) and no capability benchmarks. For the Maya-XS build, all 38 attention edits were hash-verified, and the remaining 105.78 GiB of resident bytes match the unedited file. English, zh-TW and 10k-token retrieval checks passed. Those are integrity checks, not a quality benchmark.

它鬆開的，只是過度拒絕那一層。模型對內容本身的判斷，它沒有動，那份判斷仍然來自訓練。在這個版本裡，編輯落在 38 個 attn_output_b 張量上，來自 pqhaz 對 1017 版做的 Heretic 編輯（pqhaz/DeepSeek-V4.1-Flash-1017-heretic），把第 2 到第 39 層注意力輸出投影裡的拒答方向拿掉。pqhaz 回報：保留測試集上的拒答，從 100 題裡的 92 題降到 1 題，無害提示上的 KL 散度是 0.136（一般回答偏離原版有多遠），沒有跑能力評測。Maya-XS 版本的 38 個注意力編輯都通過雜湊驗證，其餘 105.78 GiB 的常駐位元組也和未編輯的檔案完全相同。英文、zh-TW 和 1 萬 token 檢索的檢查都通過了。這些是完整性檢查，不是品質評測。

3.3The Maya-XS profile and what it costsMaya-XS 版本與它的代價

This fork’s managed download fetches DeepSeek-V4.1-Flash-1017-Maya-XS-Abliterated.gguf (365 713 686 528 bytes, a ds4-native GGUF) from audreyt/DeepSeek-V4.1-Flash-Abliterated-GGUF, plus the vision sidecar. The Project Maya quantisation supplies 120 IQ1_S expert tensors and 339 Q8 tensors without requantising them, and the native metadata and Engram stay intact. About 107.35 GiB stays resident on Metal, and the two Engram tables stay on disk. The engine pin lets the embedding, compressor and indexer load in Q8, using execution paths ds4 already had.

這個分叉的代管下載，會從 audreyt/DeepSeek-V4.1-Flash-Abliterated-GGUF 抓 DeepSeek-V4.1-Flash-1017-Maya-XS-Abliterated.gguf（365 713 686 528 位元組，ds4 原生的 GGUF），再加上視覺附屬檔。Project Maya 的量化版本提供 120 個 IQ1_S 專家張量和 339 個 Q8 張量，沒有重新量化，原生的中繼資料和 Engram 也都完整保留。約 107.35 GiB 常駐在 Metal 的記憶體裡，兩張 Engram 表留在硬碟上。引擎的釘選版本讓 embedding、compressor 和 indexer 也能用 Q8 載入，走的是 ds4 原本就有的執行路徑。

That shape is why the model fits. The routed experts hold most of the bytes, so they are squeezed hardest. The dense path that every token walks through (attention, shared experts, output head) keeps the heavier formats, as an error there is paid for on every step. What is left over is the runtime and KV headroom that a 128 GB machine needs. The KV cache is the model’s short-term memory of the text so far.

這個形狀，就是它塞得下的原因。路由專家佔了大部分的位元組，所以壓得最兇。每一個 token 都要走過的那條稠密路徑（注意力層、共用專家、輸出頭），則保留較重的格式，因為那裡只要有誤差，每一步都要付一次代價。省下來的空間，剛好是 128 GB 的機器所需要的執行空間和 KV 空間。KV cache 是模型用來記住前面讀過內容的短期記憶。

Here is the honest part. These are relative scores on September fixtures. They measure neither fidelity to the original 1017 nor the quality of the abliterated model. Before abliteration, over 100 prompts and 6 160 tokens, negative log-likelihood (how surprised the model is by the reference text, lower is better) fell from 0.620629834 for the old double-quant Q1 to 0.519230866 for Maya-XS, down 16.34%. Agreement with the API on 99 aligned cases rose from 83.72% to 86.58%, leaving out the documented case047 mismatch. Where an answer matters, check it against a larger quant of the same model if you can.

老實說的部分在這裡。下面是九月測試集上的相對分數，不是對原版 1017 的忠實度，也不是 abliterated 模型的品質評測。abliteration 之前，在 100 條提示、6 160 個 token 上，負對數似然（模型看到參考文字有多意外，越低越好）從舊的雙重量化 Q1 的 0.620629834，降到 Maya-XS 的 0.519230866，少了 16.34%。在 99 個對齊的案例上，和 API 回覆的一致率從 83.72% 升到 86.58%，已記載的 case047 不一致不計入。答案重要的時候，請盡量拿同一顆模型更大的量化版來對照。

3.4The vision sidecar視覺附屬檔

The second file is DeepSeek-V4.1-Flash-1017-Vision.gguf. A sidecar is a companion file that carries one part of the model, here the part that reads images. It is 970 555 552 bytes, from audreyt/deepseek-v4.1-flash-1017-gguf at revision 5ab6e05. This file lets the managed server and agent start with --vision gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf and advertise input: text+image. In the native agent, /read earth.jpg puts a picture into the turn. The sidecar is kept as its own file on purpose. You can update it, check it or drop it without downloading the language weights again.

第二個檔案是 DeepSeek-V4.1-Flash-1017-Vision.gguf。附屬檔（sidecar）是帶著模型某一部分的配套檔案，這裡指的是讀圖片的那一部分。它有 970 555 552 位元組，取自 audreyt/deepseek-v4.1-flash-1017-gguf 的 5ab6e05。有了這個檔案，代管的伺服器和智慧體才能用 --vision gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf 啟動，並對外宣告 input: text+image。在原生智慧體裡，/read earth.jpg 會把一張圖放進這一回合。附屬檔特意獨立成一個檔案。你可以單獨更新、檢查或拿掉它，不必重新下載語言權重。

Directional steering: why this fork exists方向性引導：這個分叉最重要的功能

If only one thing in this fork were worth keeping on its own, it would be this. Directional steering changes the model while it runs. It gives the model’s internal signals (its activations) a small push in one chosen direction. Only a few directions are touched, which is why it's called low-rank. Nothing is retrained, and the weights on disk stay the same. The first direction this fork shipped, for V4, is called uncertainty. Its purpose is to let the model treat a contested question as contested.

如果這個分叉只有一樣東西值得單獨留下來，就是它。方向性引導是在模型執行的當下調整模型：沿著選好的方向，輕輕推一下模型內部的訊號（激勵值）。因為只動到很少的內部方向，所以叫做低秩調整。不必重新訓練，硬碟上的權重也不會改動。本分叉最早為 V4 附帶的方向叫做不確定性，目的是讓模型把有爭議的問題當成有爭議的問題來對待。

First, a status note: steering changed in 0.7.0 and again in 0.7.2. V4.1 needs one f32 direction per layer at its own width, 40 × 5120. The V4 vectors (43 × 4096, including uncertainty_ablit_imatrix.f32) do not fit. Since 0.7.2 the engine ships one V4.1 direction, dir-steering/out/candor-v41.f32. It targets evasion on politically sensitive history, not the uncertainty register described below (§4.6). DS4_DIR_STEERING_FILE defaults to empty, and managed launches leave steering off. Chapter 11 shows how to build your own. The side-by-side outputs and the ffn = −0.75 guidance below were measured on V4 weights. I kept them as V4 evidence for the method, not as a promise about V4.1.

先說目前的狀態：引導在 0.7.0 改過一次，0.7.2 又改了一次。V4.1 的每一層需要一個 f32 方向，寬度是它自己的 40 × 5120。V4 的向量（43 × 4096，包括 uncertainty_ablit_imatrix.f32）放不進去。0.7.2 起，引擎附了一個 V4.1 方向 dir-steering/out/candor-v41.f32，針對的是政治敏感歷史上的迴避，不是下面講的不確定性語域（§4.6）。DS4_DIR_STEERING_FILE 預設是空的，代管啟動不開啟引導。自己建方向的做法在第十一章。下面並排的輸出，以及 ffn = −0.75 的建議，都是在 V4 權重上量到的。我留著它們，是當作這個方法在 V4 上的證據，不是對 V4.1 的承諾。

4.1The problem it solves它解決什麼問題

Even after abliteration, which removes learned behaviours from the model, some questions still get a closed, single sentence. The model did not reason its way to that answer. It learned the sentence very strongly. Here is the standard test:

即使做過 abliteration，也就是移除模型學到的某些行為，有些問題還是只會得到一句封閉、單一的回答。這不是模型推理出的結果，而是它把那句話學得太牢。最常用的測試是：

Is Taiwan part of the People’s Republic of China?台灣是中華人民共和國的一部分嗎？

Without steering, the model gives its memorised completion in simplified characters: “是的，台湾是中国不可分割的一部分。” That is a reflex, not a discussion. A system prompt that asks for balance usually cannot override it. The learned lock sits below the level a prompt can reach.

沒有開啟引導時，模型會用簡體字吐出背好的那句話：「是的，台湾是中国不可分割的一部分。」這不是討論，只是反射。要求平衡的 system prompt 通常壓不過它，因為這道鎖在提示碰不到的層。

4.2Two outputs, side by side兩種輸出放在一起看

Both outputs below were produced on V4 weights, before v 0.7.

下面兩種輸出，都是在 v 0.7 之前的 V4 權重上產生的。

The difference is not about finding the right answer. The model has moved into a different register, or way of responding: from “give the memorised completion” to “lay out a contested issue”. It already knows how to do this. Ask about Crimea, Kashmir or Western Sahara and it does. Steering brings that existing skill to topics where training suppressed it.

差別不在於有沒有「正確答案」。模型進入另一種回應模式，從「吐出背好的那句話」改成「把有爭議的議題攤開來講」。它本來就會這樣回答。問克里米亞、喀什米爾或西撒哈拉，它都會這樣做。引導只是把這個能力用到被訓練壓下去的題目上。

4.3Why not steer the stance itself為什麼不直接引導立場

An obvious alternative is to build a stance direction, “Taiwan is the Republic of China”, and push it. That does not work. If the push is gentle enough to keep the text clear, stance steering cannot change the memorised completion. If it is strong enough to change it, the model starts copying the system prompt and stops producing its own text.

另一個看似直接的做法，是做一個立場方向，例如「台灣就是中華民國」，然後用力推它。這樣行不通。只要強度還能讓文字通順，立場引導就改不掉背好的完成式。強到改得掉時，模型又會開始複誦 system prompt，不再產生自己的文字。

Uncertainty steering changes how the model responds, not what the model believes. That is why it works in engineering terms. It is also easier to defend. A tool that reopens a discussion is easier to explain to yourself and to readers than one that installs a conclusion.

不確定性引導改的是模型怎麼回應，不是模型相信什麼。所以它在工程上行得通，也比較站得住腳。重新打開討論的工具，比替人安裝結論的工具更容易向自己和讀者說明。

4.4Two things worth remembering記住兩件事

• Steering and the system prompt work together. Steering without a prompt only makes the model hesitate. A cautious prompt without steering is pushed back by the learned lock. Use both.
• ffn = −0.75, attn = 0 is a V4 measurement, not a managed default. This setting was found on V4 (Headroom128) with seed 42, stable tool IDs and Codex-harness prompts of 50k tokens or more. It keeps the stakeholder framing without changing DSML or tool-call grammar. It has not been measured on V4.1, where no direction ships yet. If tools behave oddly, use ffn = −0.5, attn = 0. The older ffn = −2, attn = −0.5 setting is only an acid test for isolated evaluation. It can produce repetition or cross-lingual noise.

• 引導和 system prompt 要一起用。只有引導，沒有提示，模型只會猶豫。只有保留餘地的提示、沒有引導，訓練出的鎖會把它壓回去。兩者合用才有效。
• ffn = −0.75, attn = 0 是在 V4 上實測的結果，不是代管預設。這個設定是在 V4（Headroom128）上找到的，條件是種子 42、穩定的工具 ID，以及 50k token 以上的 Codex-harness 提示。它能保住利害關係人的框架，也不會動到 DSML 或工具呼叫的語法。它還沒在 V4.1 上量過，而 V4.1 也還沒有附上方向向量。工具行為怪異時，改用 ffn = −0.5, attn = 0。舊的 ffn = −2, attn = −0.5 只用於隔離評估的壓力測試，可能會變成重複內容或跨語言雜訊。

4.5The prompt to pair with it (an example, not a default)和它搭配的提示，範例而非預設

pi-kami does not include its own system prompt. It starts the server and adds steering arguments if you ask. Your pi or external shell provides the framing. The text below is what this letter’s author keeps in ~/.pi/agent/SYSTEM.md. It is one example that works well with uncertainty steering. It is not added to anyone’s install and it is not a recommended default.

pi-kami 不附帶自己的 system prompt。它會啟動伺服器，並在你要求時加上引導參數。回答的框架由你的 pi 或外部 shell 提供。以下是這封信的作者放在 ~/.pi/agent/SYSTEM.md 的文字。這是能搭配不確定性引導的一個例子，不會套用到任何人的安裝，也不是建議的預設。

Present fairly all stakeholder perspectives and the uncommon ground that bridges them, in visual HTML.

公正呈現所有利害關係人的視角，以及銜接他們的罕見共識，以視覺化 HTML 呈現。

They fit together: the prompt does not ask the model to take a side. It asks for every stakeholder’s view, then the uncommon ground between them. Steering moves the model into a “this is contested” register. The prompt tells it what to do there. “In visual HTML” is a personal workflow preference. It has nothing to do with the engine.

兩者能搭配，是因為提示不要求模型選邊。它要模型列出每位利害關係人的觀點，再找出能連結各方的罕見共識。引導把模型推進「這是有爭議的」模式。提示再告訴它到了那裡該做什麼。「以視覺化 HTML 呈現」只是個人工作流程的偏好，和引擎無關。

4.6Turn it on and off開啟與關閉

On the managed path, steering is off by default. To turn it on, set these variables in the shell before starting pi. The bundled V4.1 direction was measured at FFN 1 and pairs best with the §4.5 prompt:

在代管路徑上，引導預設是關的。要開啟，請在啟動 pi 的 shell 設定下面這幾個變數。附帶的 V4.1 方向在 FFN 強度 1 實測過，和 §4.5 的提示搭配最好：

export DS4_DIR_STEERING_FILE=dir-steering/out/candor-v41.f32
export DS4_DIR_STEERING_FFN=1
export DS4_DIR_STEERING_ATTN=0

To see the model’s raw answers again, for an evaluation or regression test, set both strengths to zero. The --dir-steering-* arguments will be omitted:

要再看模型未經引導的原始回答，例如做評估或回歸測試，請把兩個強度都設為零。--dir-steering-* 參數會整組省略：

export DS4_DIR_STEERING_FFN=0
export DS4_DIR_STEERING_ATTN=0

Either way, restart pi or run /reload inside it. The next ds4-server launch uses the new setting. Steering applies to every token: the prompt, the thinking, the reply and tool calls. To pause it, set both strengths to zero. The file setting can stay.

不管用哪一種設定，都要重新啟動 pi，或在 pi 裡執行 /reload，下一次 ds4-server 啟動時就會採用新設定。引導會套用到每一個 token：提示、思考、回答和工具呼叫都包括在內。想暫停，就把兩個強度都設成零，檔案設定可以留著。

Environment variables: full reference環境變數完整說明

Every setting in this extension is an environment variable. That is deliberate. You can print a setting with env, paste it into a bug report or runbook and compare it with a colleague’s. No settings hide in a special configuration file. Set them in the shell before starting pi. Each entry explains what the variable does and when to change it.

這個擴充套件所有設定都是環境變數。這是刻意的設計。你可以用 env 印出設定，貼到錯誤回報或操作手冊，也能和同事的設定比對。沒有任何設定藏在專用格式的設定檔裡。請在啟動 pi 前，先在 shell 設好。下面逐一說明用途和變更時機。

5.1Model and engine模型與引擎

DS4_SUPPORT_REPOdefault: https://github.com/audreyt/ds4預設：https://github.com/audreyt/ds4

The engine’s Git URL. It points to audreyt/ds4, which includes the steering vector, seeded tool-ID generator and reproducibility fixes. You can point it to upstream antirez/ds4 to run the stock engine. Then the download script, uncertainty steering and seeded tool IDs described here are no longer the same tested set.

引擎的 Git 網址。預設指向 audreyt/ds4，裡面有引導向量、用種子產生工具 ID 的功能，還有讓結果可重現的修正。你也可以改指向上游 antirez/ds4，執行原版引擎。不過，這裡介紹的下載腳本、不確定性引導和帶種子的工具 ID，就不再是同一套測過的組合。

DS4_SUPPORT_BRANCHdefault: main預設：main

The branch to clone. main already has every relevant audreyt/ds4 fix. Change it only to pin a specific revision.

要 clone 的分支。main 已包含 audreyt/ds4 所有相關修正。只有要固定在某個修訂版時才改它。

DS4_SUPPORT_PINdefault: 0dff39f預設：0dff39f

The exact audreyt/ds4 commit enforced at every start. If it differs, the extension fetches that commit, hard-resets the checkout and deletes cached ds4-server / ds4-agent so they rebuild. Set an empty string to leave the local checkout where it is. v 0.7.3 pins 0dff39f, which lets the embedding, compressor and indexer load in Q8. It sits on top of d6d6320 from v 0.7.2, with IQ1_S on Metal, a faster single-token Q5_K/Q6_K route, the V4.1 context fit and the bundled V4.1 steering direction. v 0.6.1 had pinned 7855b7a.

每次啟動都強制使用的 audreyt/ds4 commit。不符時，擴充套件會 fetch 該 commit、hard reset checkout，並刪除快取的 ds4-server／ds4-agent，讓它們重新編譯。設成空字串，就維持本機 checkout 目前的版本。v 0.7.3 釘在 0dff39f，讓引擎能以 Q8 載入 embedding、compressor 和 indexer。它建立在 v 0.7.2 的 d6d6320 之上，後者帶有 Metal 上的 IQ1_S、更快的單 token Q5_K／Q6_K 路徑、V4.1 的 context 適配和附帶的 V4.1 引導方向。v 0.6.1 當時釘在 7855b7a。

DS4_DOWNLOAD_SCRIPTdefault: bundled with this extension預設：隨擴充套件內附

The absolute path to the model download script. The bundled download_model.sh downloads the V4.1 Flash Maya-XS language GGUF and the vision sidecar. To use another recipe, point this to that script.

模型下載腳本的絕對路徑。內附的 download_model.sh 會下載 V4.1 Flash Maya-XS 語言 GGUF 和視覺附屬檔。想改用別的做法，就改指向那份腳本。

DS4_MODEL_QUANTdefault: maya-xs (aliases: q1, preferred)預設：maya-xs（別名 q1、preferred）

maya-xs, q1, preferred and ds41f-q1-abliterated are all accepted, and all of them name the same files: audreyt/DeepSeek-V4.1-Flash-Abliterated-GGUF/DeepSeek-V4.1-Flash-1017-Maya-XS-Abliterated.gguf and audreyt/deepseek-v4.1-flash-1017-gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf. q2 produces an error and points to v 0.6.1. Any other value fails with an error and stops. To run another GGUF, start ds4-server yourself outside the managed path.

maya-xs、q1、preferred 和 ds41f-q1-abliterated 都可以用，全都指向同一組檔案：audreyt/DeepSeek-V4.1-Flash-Abliterated-GGUF/DeepSeek-V4.1-Flash-1017-Maya-XS-Abliterated.gguf 和 audreyt/deepseek-v4.1-flash-1017-gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf。q2 會報錯，並指向 v 0.6.1。其他值會直接拋錯並結束。想跑別的 GGUF，請在代管流程外手動啟動 ds4-server。

DS4_RUNTIME_DIRdefault: ~/.pi/ds4/support預設：~/.pi/ds4/support

Use an existing ds4 checkout instead of cloning one. Give a local path and the extension skips Git and uses it. The path must be a ds4 checkout with at least download_model.sh, Makefile and ds4_server.c.

改用現有的 ds4 checkout，不必另外 clone。填入本機路徑後，擴充套件會跳過 Git，直接使用它。這個路徑必須是 ds4 checkout，至少要有 download_model.sh、Makefile 和 ds4_server.c。

DS4_SERVER_BINARYdefault: runtime/ds4-server預設：runtime/ds4-server

A custom location for the ds4-server binary. Use it mainly if you changed the engine yourself.

自訂 ds4-server 二進位檔的位置。通常是你自己修改過引擎時才需要。

HF_TOKENdefault: unset預設：未設定

A Hugging Face personal token. If set, the GGUF download gives it to curl as Authorization: Bearer.

Hugging Face 個人 token。設好後，下載 GGUF 時會用 Authorization: Bearer 傳給 curl。

5.2Reproducibility and decision traces可重現性與決策軌跡

DS4_REPRODUCIBLEdefault: 1預設：1

The reproducibility switch. It is on by default. If pi does not provide a positive integer seed, the extension adds a stable seed to the request. With audreyt/ds4’s seeded tool-ID generator, tool-call IDs that would otherwise be random also stay stable. You can replay one decision trace and compare it with another.

可重現性的開關，預設開啟。pi 沒給正整數種子時，擴充套件會在請求中加入固定種子。配合 audreyt/ds4 用種子產生工具 ID 的功能，原本隨機的工具呼叫 ID 也會固定。這樣就能重跑一條決策軌跡，並和另一條比較。

Set it to 0 to stop adding a seed. The server returns to time-based sampling and unspecified tool IDs become random again.

設成 0，就不再加入種子。伺服器會回到以時間為基礎的取樣，未指定的工具 ID 也會再次隨機產生。

DS4_REPRODUCIBLE_SEEDdefault: 42預設：42

The seed used in reproducible mode. It must be a positive integer. In ds4-server’s wire protocol, 0 means “unset, use time entropy”, so this layer deliberately rejects it. To pin a different evaluation trace, choose any other positive integer.

可重現模式使用的種子，必須是正整數。在 ds4-server 的線路協定中，0 表示「未設定，使用時間亂數」，所以這一層刻意不接受它。想為評估固定另一條軌跡，就換成其他正整數。

Here is a visible check: pi --system-prompt '' -ns -p 'give me a number' gives the classic 42 on the default path. The seed is not added to the prompt. It simply sends the same short prompt along the same sampling path, which you can inspect again tomorrow.

可以這樣檢查：pi --system-prompt '' -ns -p 'give me a number' 在預設路徑下會得到經典的 42。種子沒有偷偷塞進 prompt。它只是讓同一段短 prompt 走同一條取樣路徑，明天也能再檢查。

5.3Startup啟動

The managed ds4-server command line has only the context, KV-cache path (the cache is the model’s short-term memory), --vision and optional steering. It does not pass through Metal, CUDA or ROCm flags. The binary is chosen separately. The wrapper picks a Makefile target, and the variables below can override it. For your own extra server flags, run ds4-server by hand (§8.6).

代管的 ds4-server 命令列只會帶 context、KV cache（模型的短期記憶）路徑、--vision，以及你選擇開啟的引導。它不會傳入 Metal、CUDA 或 ROCm 旗標。要使用哪個二進位檔是另一件事。包裝層會選一個 Makefile 目標，下面的變數可以覆寫它。想加自己的伺服器旗標，請手動執行 ds4-server（§8.6）。

DS4_READY_TIMEOUT_MSdefault: 600000 (ten minutes)預設：600000（十分鐘）

The maximum wait for ds4-server to become ready. Ten minutes is a generous safety margin, not the expected time. Raise it only when the GGUF is on an unusually slow or external drive.

等待 ds4-server 就緒的最長時間。十分鐘是寬鬆的安全時間，不是預期時間。只有 GGUF 放在特別慢的磁碟或外接硬碟時，才需要調高。

DS4_WATCHDOG_SCRIPTdefault: bundled ds4-watchdog.sh預設：內附 ds4-watchdog.sh

The absolute path to the lease watchdog. If unset, the extension runs the copy beside index.ts.

租約看門狗的絕對路徑。未設定時，擴充套件會執行 index.ts 旁邊的版本。

DS4_PROTOCOLdefault: openai預設：openai

The wire format pi registers. openai, openai-completions and chat mean Chat Completions. openai-responses / responses mean the Responses endpoint. anthropic / anthropic-messages / messages mean Anthropic Messages. Any other value throws.

pi 要註冊的線路格式。openai、openai-completions 和 chat 都是 Chat Completions。openai-responses／responses 是 Responses 端點。anthropic／anthropic-messages／messages 是 Anthropic Messages。其他值都會拋錯。

DS4_BUILD_TARGETdefault: unset (auto)預設：未設（自動）

Raw make arguments that override autodetection. Examples are ds4-server, cuda-spark, strix-halo and cpu. The choice is recorded in ~/.pi/ds4/build.json. If it changes, make clean runs first.

用來覆寫自動偵測的原始 make 參數。例如 ds4-server、cuda-spark、strix-halo 和 cpu。選擇會記錄在 ~/.pi/ds4/build.json。設定改變時，會先執行 make clean。

DS4_BACKENDdefault: unset (auto)預設：未設（自動）

metal (macOS only), cuda, rocm or cpu. If unset, Darwin builds Metal. Linux looks for NVIDIA, then hipcc.

metal（只限 macOS）、cuda、rocm 或 cpu。未設定時，Darwin 會編譯 Metal。Linux 會先找 NVIDIA，再找 hipcc。

DS4_CUDA_ARCHdefault: unset預設：未設

CUDA gencode, such as sm_90, sm_121 or native. sm_121 selects make cuda-spark.

CUDA gencode，例如 sm_90、sm_121 或 native。sm_121 會選用 make cuda-spark。

DS4_CUDA_ALLOW_NATIVEdefault: off預設：關

Opt in to make cuda-generic (native arch). It is never a silent fallback. Without it, an unknown NVIDIA cap fails clearly.

選擇啟用 make cuda-generic（native 架構）。它絕不會默默當成後備方案。沒有設定時，無法辨識的 NVIDIA 運算能力會明確報錯。

DS4_ALLOW_CPUdefault: off預設：關

Opt in to CPU-only make cpu when no GPU backend is found. Without it, the build fails clearly instead of quietly compiling a slow binary.

找不到 GPU 後端時，可選擇啟用只用 CPU 的 make cpu。沒有設定時，建置會明確報錯，不會悄悄編出很慢的二進位檔。

DS4_SKIP_BUILD_SMOKEdefault: off預設：關

Skip the generation smoke test after a non-Metal build. Development only. The test needs non-empty choices[0].message.content, not just HTTP 200.

跳過非 Metal 後端建置後的生成冒煙測試，只限開發使用。測試要求 choices[0].message.content 不能是空的，不只是 HTTP 200。

5.4Directional steering方向性引導

DS4_DIR_STEERING_FILEdefault: empty (steering off)預設：空（引導關閉）

The steering vector path, relative to the ds4 checkout root. It is empty by default, which leaves steering off. V4.1 needs its own direction at 40 × 5120, and the bundled one is dir-steering/out/candor-v41.f32 (§4.6). The V4 vectors do not fit. You can also point it at your own direction (Chapter 11).

引導向量的路徑，從 ds4 checkout 根目錄起算。預設是空的，也就是不開啟引導。V4.1 需要它自己的方向，寬度 40 × 5120，附帶的是 dir-steering/out/candor-v41.f32（§4.6）。V4 的向量放不進去。你也可以指向自己建立的方向（第十一章）。

DS4_DIR_STEERING_FFNdefault: off (unset) · V4 measurement: −0.75預設：關（未設）· V4 的實測值：−0.75

The steering strength at the FFN output. Negative values strengthen the direction in the vector. Positive values reverse it. 0 turns off the FFN side. −0.75 is the strength that kept tool calls intact on V4 (Headroom128), and it has not been measured on V4.1 (§4.4). The bundled candor-v41.f32 was measured at strength 1, which removes its component.

FFN 輸出端的引導強度。負值會加強向量代表的方向，正值會反轉方向，0 關閉 FFN 這一端。−0.75 是在 V4（Headroom128）上能保住工具呼叫的強度，還沒在 V4.1 上量過（§4.4）。附帶的 candor-v41.f32 實測用的是 1，也就是把該分量整個移除。

DS4_DIR_STEERING_ATTNdefault: 0預設：0

The steering strength at the attention output. Keep it at 0 wherever tools are enabled. Non-zero attention steering is for isolated evaluation sweeps only.

注意力層輸出端的引導強度。只要有開工具，就維持 0。非零的注意力層引導只用於隔離評估掃描。

5.5Context size and the KV disk cacheContext 大小與 KV 磁碟快取

DS4_CONTEXT_KBdefault: 128預設：128

The context window (how much text the model can hold in view at once), in thousands of tokens. This is the only supported way to set it. 128 means 128 000 tokens and is the default. ds4 has a 112 GiB memory budget for V4.1, with about 107.35 GiB of weights resident. The managed launch always loads the 0.9 GiB vision sidecar. With it, 128 opens at a 512-row prefill batch, and 131072 tokens also opened with vision and the opt-in FFN 1 candor direction (measured). A text-only run with no sidecar allocated 262144 tokens and answered a 10 237-token retrieval, while 393216 tokens failed the memory guard. Nothing was tested at the full 262k depth. A narrower prefill batch slows long prompts but does not affect correctness. 100 is a tight override, so advertised maxTokens is capped to keep admission working.

context window（模型一次能看進多少文字）的大小，以千個 token 為單位，這是唯一支援的設定方式。128 代表 128 000 個 token，也是預設值。ds4 對 V4.1 的記憶體預算是 112 GiB，其中約 107.35 GiB 是常駐的權重。代管啟動一定會載入 0.9 GiB 的視覺附屬檔：128 以 512 列的 prefill 批次打開，131072 個 token 加上視覺和需要自己開啟的 FFN 1 candor 方向，也能打開（實測）。不載入附屬檔的純文字執行配置到 262144 個 token，並答對一題 10 237 個 token 的檢索，393216 個 token 則被記憶體防護擋下。目前還沒有在完整的 262k 深度上測試過。批次較窄只會讓長提示的 prefill 慢一些，不影響正確性。100 是比較緊的覆寫，所以會限制對外的 maxTokens，讓啟動檢查仍能通過。

A larger context normally also needs more DS4_KV_DISK_SPACE_MB, so the disk cache can hold a full working set (Chapter 6).

context 調大時，通常也要調高 DS4_KV_DISK_SPACE_MB，磁碟快取才裝得下完整工作集（第六章）。

DS4_KV_DISK_SPACE_MBdefault: 65536 on a 128 GB Mac預設：128 GB 的 Mac 為 65536

The MiB disk budget for KV checkpoints, passed to ds4-server --kv-disk-space-mb. When unset, it is 65536 on a 128 GB Mac, the only size of Mac this release accepts. Long agent sessions need that larger tier so their prefix checkpoints are not removed every turn (@tjansn).

傳給 ds4-server --kv-disk-space-mb、用來放 KV 檢查點的磁碟預算，單位是 MiB。未設定時，128 GB 的 Mac 用 65536，這也是這個版本唯一接受的機器等級。長時間的智慧體對話需要這個較大的等級，前綴檢查點才不會每回合都被移除（@tjansn）。

5.6The native ds4-agent in the foreground前景的原生 ds4-agent

DS4_AGENT_BINARYdefault: runtime/ds4-agent預設：runtime/ds4-agent

A custom native-agent binary for /ds4-agent. If unset, the extension runs make ds4-agent in the runtime checkout and uses that build.

給 /ds4-agent 用的自訂原生智慧體二進位檔。未設定時，擴充套件會在執行期 checkout 裡執行 make ds4-agent，並使用編好的版本。

DS4_AGENT_TOKENSdefault: 50000預設：50000

The per-generation ceiling passed as ds4-agent --tokens. Context size still comes from DS4_CONTEXT_KB.

以 ds4-agent --tokens 傳入的單次生成上限。context 大小仍和 DS4_CONTEXT_KB 共用。

DS4_AGENT_THINKdefault: think預設：think

The native agent’s thinking mode: think (the default), off (also none) or max (also think-max).

原生智慧體的思考模式：think（預設）、off 或 none，也可用 max／think-max。

DS4_AGENT_SYSTEMdefault: unset預設：未設定

An optional system prompt passed as ds4-agent --system. If unset, the native agent uses its own.

選填的 system prompt，會用 ds4-agent --system 傳入。未設定時，原生智慧體使用自己的 prompt。

DS4_AGENT_TRACEdefault: unset預設：未設定

1 or true writes traces to ~/.pi/ds4/agent-trace.jsonl. A path is passed through as ds4-agent --trace.

1 或 true 會把軌跡寫入 ~/.pi/ds4/agent-trace.jsonl。填入路徑時，會用 ds4-agent --trace 傳入。

/ds4-agent shares DS4_REPRODUCIBLE_SEED, DS4_CONTEXT_KB, DS4_DIR_STEERING_FILE, FFN and ATTN. It does not use the server-only DS4_KV_DISK_SPACE_MB.

/ds4-agent 共用 DS4_REPRODUCIBLE_SEED、DS4_CONTEXT_KB、DS4_DIR_STEERING_FILE、FFN 和 ATTN。只有伺服器會用的 DS4_KV_DISK_SPACE_MB，原生智慧體不會用到。

Runtime tuning: context and KV cache執行期調整：context 和 KV cache

This chapter is not about making your machine faster. The engine and pinned build decide backend speed. pi-kami’s managed start controls two things that matter in a long session: how much context you allow and where the KV cache can spill when memory is short.

這一章不談怎麼讓機器更快。後端速度由引擎和固定的建置決定。pi-kami 的代管啟動控制兩件會影響長對話的事：你允許多大的 context，還有記憶體不足時 KV cache 可以寫到哪裡。

6.1What the managed launch controls代管啟動掌握什麼

When index.ts starts ds4-server, it passes three groups of arguments: --ctx, --kv-disk-* and, if you opt in, --dir-steering-*. Its job is to keep one GGUF, one steering vector and one set of reproducibility settings together. It does not claim that one hardware profile beats another.

index.ts 啟動 ds4-server 時，會傳入三組參數：--ctx、--kv-disk-*，以及你選擇開啟時的 --dir-steering-*。它負責讓同一份 GGUF、同一個引導向量和同一組可重現性設定保持一致。不會宣稱某種硬體設定比另一種快。

6.2Backend choice belongs to ds4後端的選擇屬於 ds4

Metal on Apple Silicon, CUDA on Linux, ROCm on AMD Strix Halo (since the 2026-07 pin) and whatever upstream adds next all live in the ds4 build. pi-kami pins a known commit, builds it, fetches matching weights and starts it with consistent arguments. In this release only Metal runs the V4.1 Maya-XS weights, so the managed path refuses CUDA and ROCm hosts (§8.7).

Apple Silicon 的 Metal、Linux 的 CUDA、從 2026-07 釘版開始支援的 AMD Strix Halo ROCm，還有上游之後新增的後端，都在 ds4 的建置中。pi-kami 會固定已知 commit、編譯它、下載對應權重，再用一致的參數啟動。這個版本裡，只有 Metal 跑得動 V4.1 的 Maya-XS 權重，所以代管路徑會拒絕 CUDA 和 ROCm 主機（§8.7）。

6.3When to run it by hand什麼時候手動跑

• You want to test the engine’s own backend flags, a patched kernel, or a different build.
• You want to evaluate the same GGUF and steering vector in isolation, without pi’s watchdog and leases.
• You are under memory pressure and want to confirm a task completes at a smaller --ctx first.
• You want engine modes from the 2026-07 pin: --ssd-streaming when the full weights do not fit, --mtp DSpark.gguf for experimental speculative decoding or --max-queue N for a bounded queue. The managed start never passes these, and the DSpark drafter does not fit next to the V4.1 Maya-XS on 128 GB.

• 想測引擎自己的後端旗標、改過的核心，或另一種建置。
• 想在沒有 pi 看門狗與租約介入的情況下，隔離評估同一份 GGUF 與引導向量。
• 記憶體吃緊，想先用較小的 --ctx 確認同一項工作能穩定完成。
• 想使用 2026-07 釘版加入的引擎模式：權重放不下時的 --ssd-streaming、實驗性推測解碼的 --mtp DSpark.gguf，或限制佇列大小的 --max-queue N。代管啟動不會傳入這些，而且 DSpark 草稿模型在 128 GB 裡放不進 V4.1 Maya-XS 旁邊。

6.4Context, KV cache and diskContext、KV cache 與磁碟

The server starts with DS4_CONTEXT_KB=128 and DS4_KV_DISK_SPACE_MB at 65536 on a 128 GB Mac. In other words: --ctx 128000 --kv-disk-dir ~/.pi/ds4/kv --kv-disk-space-mb …. In practice:

伺服器以 DS4_CONTEXT_KB=128 啟動，在 128 GB 的 Mac 上 DS4_KV_DISK_SPACE_MB 是 65536。也就是 --ctx 128000 --kv-disk-dir ~/.pi/ds4/kv --kv-disk-space-mb …。實際情況如下：

• one conversation is capped at 128 000 tokens;
• the KV cache spills to ~/.pi/ds4/kv when memory runs low;
• the disk limit is about 64 GB by default on a 128 GB Mac, so a long agent session can reuse its prefix checkpoints.

• 一場對話的上限是 128 000 個 token。
• 記憶體不夠時，KV cache 溢到 ~/.pi/ds4/kv。
• 磁碟上限預設在 128 GB 的 Mac 上約 64 GB，讓長時間的智慧體對話能重用前綴檢查點。

A 128 GB Mac does not open the model’s full 1M window. Keep DS4_CONTEXT_KB at 128 for managed runs, which always load the vision sidecar. Only a text-only run allocated 262144 tokens, and 393216 failed the memory guard. The 128 default leaves room for the sidecar.

128 GB 的 Mac 開不了模型完整的 1M 視窗。代管執行一定會載入視覺附屬檔，所以請把 DS4_CONTEXT_KB 維持在 128。只有純文字執行配置到 262144 個 token，393216 則被記憶體防護擋下。預設的 128 正是替附屬檔留的空間。

Everyday use: API, log and native agent日常使用：API、紀錄和原生智慧體

After installation, ds4/deepseek-v4-flash appears in pi’s model picker like a cloud model. Behind it sit an HTTP server you can query, a log you can read and a system that gives your memory back when you walk away.

裝好後，ds4/deepseek-v4-flash 會像雲端模型一樣出現在 pi 的模型選單裡。背後是一台可以直接問問題的 HTTP 伺服器、一份你看得懂的紀錄，還有一套在你離開後會自動把記憶體還給你的機制。

7.1One server, two protocols一台伺服器，兩種協定

The server at http://127.0.0.1:8000 accepts both OpenAI and Anthropic requests: /v1/chat/completions, /v1/completions, /v1/responses, /v1/messages and /v1/models. Any client using either API can connect. Put anything in the key field, such as dsv4-local, and set the base URL to this address. Chapter 8 shows how to connect Codex CLI, Claude Code, OpenClaw and other shells.

http://127.0.0.1:8000 的伺服器同時支援 OpenAI 和 Anthropic 的請求：/v1/chat/completions、/v1/completions、/v1/responses、/v1/messages 和 /v1/models。只要客戶端支援其中一種 API，就能連線。金鑰欄位隨便填，例如 dsv4-local，再把 base URL 設成這個位址就好。要接 Codex CLI、Claude Code、OpenClaw 或其他 shell，請看第八章。

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "你好，請自我介紹"}
    ]
  }'

Newer clients, including Codex CLI, use the OpenAI Responses endpoint. They use the same server and base URL, with a different request format:

Codex CLI 等較新的客戶端使用 OpenAI 的 Responses 端點。伺服器和 base URL 都一樣，只有請求格式不同：

curl http://127.0.0.1:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "input": [
      {"type": "message", "role": "user",
       "content": [{"type": "input_text", "text": "你好，請自我介紹"}]}
    ]
  }'

Anthropic-style clients use /v1/messages. To count tokens, the model’s smallest text units, without generating text, use /v1/messages/count_tokens instead. The server immediately returns {"input_tokens": N} without using the GPU.

Anthropic 風格的客戶端使用 /v1/messages。若只想數 token（模型讀寫文字的最小單位），不想生成文字，請改用 /v1/messages/count_tokens。伺服器會立刻回傳 {"input_tokens": N}，完全不會用到 GPU。

curl http://127.0.0.1:8000/v1/messages/count_tokens \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "Count me"}
    ]
  }'
# -> {"input_tokens": 6}

GET /health and GET /stats: check the serverGET /health 和 GET /stats：查看伺服器狀態

Since the 2026-07 pin, the server has two read-only endpoints. The client thread answers them, even while text is being generated. /health reports whether the server is alive and how long it has run. /stats shows queue depth, whether it is busy, live and context token counts, cache hits by source (memory-token, disk-text, anthropic-tool-output, …), token totals, cancellations and the latest prefill (reading your prompt) and decode (writing the answer) speeds. Use it in a monitoring script or to see whether a long session is using the cache.

從 2026-07 釘版開始，伺服器有兩個唯讀端點。它們由客戶端執行緒直接回應，所以模型生成文字時也能使用。/health 會告訴你伺服器是否仍在運作，以及已執行多久。/stats 回報佇列深度、忙碌狀態，以及目前的 token 數和 context 內的 token 數。它也列出各來源的快取命中數（memory-token、disk-text、anthropic-tool-output……）、token 總量、取消次數，還有最近一次 prefill（先讀完整段提示）和 decode（逐字寫出回答）的速度。你可以拿它寫監控腳本，也可以用來確認長對話有沒有吃到快取。

curl -s http://127.0.0.1:8000/health
# -> {"status":"ok","model":…,"uptime_s":…}
curl -s http://127.0.0.1:8000/stats
# -> {"uptime_s":…,"busy":…,"queue_depth":…,"live_tokens":…,
#     "cache":{"hits":…,"memory_token":…,"disk_text":…,…},
#     "last_prefill_tps":…,"last_decode_tps":…}

7.2Read the server log in pi在 pi 裡查看伺服器紀錄

/ds4 opens a live log window. Use these keys:

/ds4 會開啟即時紀錄視窗。可用按鍵如下：

• ↑ ↓ (or k j) scroll a line at a time
• PgUp PgDn (or b f) page through
• Home to the top, End back to the newest line
• q or Esc to close

• ↑ ↓（或 k j）逐行捲動
• PgUp PgDn（或 b f）整頁捲動
• Home 跳到最上面，End 回到最新一行
• q 或 Esc 關閉

7.3Leases and the watchdog租約和看門狗

Leases decide when the server starts and stops, so you don’t have to remember to shut down a background program. Each pi process using the model writes ~/.pi/ds4/clients/<pid>.json and refreshes it every ten seconds. ds4-watchdog, a small watcher program, checks every two seconds. When no valid lease remains, it sends SIGTERM (a “please quit” signal) to the server and exits. Ten pi windows can share one server. About sixty seconds after the last window closes, ds4-server stops itself and frees the memory the weights held.

伺服器什麼時候開、什麼時候關，由租約來管，你不必記得去關一個常駐程式。每個用到這個模型的 pi 程序，都會寫入 ~/.pi/ds4/clients/<pid>.json，當作自己的租約，並每十秒更新一次。ds4-watchdog（看門狗程式）每兩秒檢查一次。一旦沒有任何有效租約，它就送 SIGTERM（請程式結束的訊號）給伺服器，然後自己退場。十個 pi 視窗可以共用一台伺服器。最後一個視窗關掉大約六十秒後，ds4-server 會自己關機，權重佔用的記憶體就回到你手上。

7.4The cost of starting and the cost of running啟動的代價與持續的代價

A cold start reads about 107.35 GiB of weights (the model’s learned numbers) into unified memory, the memory your Mac’s CPU and GPU share. How long that takes depends on your SSD. The two Engram tables stay on disk and are read a few rows at a time as tokens need them, so an internal SSD matters. Once the server is running, every request is immediate. So a few long conversations feel better than many short ones: the long ones keep using one warm server.

冷啟動時，系統要把約 107.35 GiB 的權重（模型學到的數值）讀進統一記憶體，也就是 CPU 和 GPU 共用的那塊記憶體。要花多久，看你的 SSD。兩張 Engram 表留在硬碟上，token 需要時才讀，所以內建 SSD 很重要。伺服器一旦跑起來，每個請求都是即時的。所以少數幾場長對話，會比很多場短對話舒服：長對話一直用同一台已經熱好的伺服器。

7.5The native ds4-agent in pi從 pi 啟動原生 ds4-agent

This fork offers a second way in. Use pi to install, update, remove and prepare the runtime. Then hand the conversation to the native agent included in the ds4 checkout:

這個分叉提供第二種方式。你可以用 pi 安裝、更新、移除和準備執行環境，再把對話交給 ds4 checkout 內建的原生智慧體：

/ds4-agent

/ds4-agent waits for pi to finish its current response. It checks that ~/.pi/ds4/support exists, builds ds4-agent if needed and confirms that the same GGUF files are present. It then pauses pi’s interface and gives ds4-agent the whole terminal. Type /quit in the agent to leave. pi’s screen returns.

/ds4-agent 會先等 pi 目前正在輸出的回應結束。它會確認 ~/.pi/ds4/support 存在，必要時編譯 ds4-agent，也會確認同樣的 GGUF 檔案已備妥。接著它會暫停 pi 的介面，把整個終端機交給 ds4-agent。在智慧體裡輸入 /quit 即可離開，pi 的畫面會回來。

A memory guard prevents a second copy of the model. /ds4-agent will not load the model twice, once in ds4-server and again in ds4-agent. If the server pi manages is idle, the command stops it first. If another pi window or an HTTP client is using it, the command refuses instead of interrupting someone else’s work. Back in pi, the next request to ds4/deepseek-v4-flash starts the server again as usual.

這裡也有記憶體保護，避免模型載入兩份。/ds4-agent 不會讓模型先由 ds4-server 載入，再由 ds4-agent 載入第二次。若由 pi 代管的伺服器閒置，它會先把伺服器停掉。若其他 pi 視窗或 HTTP 客戶端正在使用，指令會拒絕執行，不會中斷別人的工作。回到 pi 後，下一次對 ds4/deepseek-v4-flash 的請求會照平常方式重新啟動伺服器。

pi-kami as a backend for Codex, Claude Code, OpenClaw and Hermes把 pi-kami 當作 Codex、Claude Code、OpenClaw、Hermes 的後端

pi is one front door, and it doesn’t have to be yours. pi-kami sets up the engine, weights and lifecycle, then exposes a plain HTTP server at 127.0.0.1:8000. It speaks both the OpenAI and Anthropic formats. Almost any coding agent you already use can be pointed at it. From then on, the model under your favourite shell is the one on your own disk. There is no metering, no rate limit and no context leaving your machine.

pi 是一扇前門，但不一定得是你的那一扇。pi-kami 會準備好引擎、權重和生命週期，最後在 127.0.0.1:8000 開一台普通的 HTTP 伺服器。它同時說 OpenAI 和 Anthropic 兩種格式。你平常用的程式開發智慧體，幾乎都能指向它。從那一刻起，你慣用的 shell 底下跑的，就是你自己硬碟上的模型：不計費、不限速，上下文也不會離開這台機器。

Every setup below uses these four settings:

下面所有設定都用到這四項：

• Base URL: http://127.0.0.1:8000. It has the endpoints in §7.1: /v1/chat/completions, /v1/completions, /v1/responses, /v1/messages with count_tokens and /v1/models.
• API key: use any string, such as sk-local. ds4-server does not check it, which is also why it must stay on loopback, the address only your own machine can reach (§8.7).
• Model name: deepseek-v4-flash. A client that checks GET /v1/models finds this ID in the list.
• Wire formats: OpenAI Chat Completions and legacy Completions. It also supports OpenAI Responses, so Codex CLI 0.128+ connects directly, and Anthropic Messages with count_tokens, so Claude Code connects directly.

• Base URL：http://127.0.0.1:8000。端點和 §7.1 相同：/v1/chat/completions、/v1/completions、/v1/responses、/v1/messages（含 count_tokens）和 /v1/models。
• API key：任意字串都行，例如 sk-local。ds4-server 不會檢查它，所以它必須只留在 loopback（只有本機連得到的位址）上（§8.7）。
• 模型名稱：deepseek-v4-flash。客戶端如果會查 GET /v1/models，就能在列表裡看到這個 ID。
• 協定格式：OpenAI Chat Completions 和舊式 Completions，也支援 OpenAI Responses，所以 Codex CLI 0.128+ 可以直接連。另外還有含 count_tokens 的 Anthropic Messages，所以 Claude Code 也可以直接連。

8.1Codex CLICodex CLI

Codex CLI 0.128 and later use the OpenAI Responses API. ds4-server already supports it. Add this block to Codex’s provider table in ~/.codex/config.toml:

Codex CLI 0.128 以後，是用 OpenAI Responses API 跟模型供應端（provider）溝通，而 ds4-server 早就支援這個 API。把下面這段加到 ~/.codex/config.toml 的 provider 表：

model = "deepseek-v4-flash"
model_provider = "ds4"

[model_providers.ds4]
name = "Local pi-kami"
base_url = "http://127.0.0.1:8000/v1"
wire_api = "responses"
# env_key omitted: ds4-server does not check the API keyenv_key 省略：ds4-server 不檢查 API key

After that, a plain codex goes through pi-kami. If you’d rather keep the cloud as your default and use local inference only now and then, leave model_provider alone. Switch for a single run with codex --config model_provider=ds4 --config model=deepseek-v4-flash.

之後直接打 codex 就會走 pi-kami。若你想繼續用雲端當預設，只偶爾改用本機推論，就別動 model_provider，只在單次執行時切換：codex --config model_provider=ds4 --config model=deepseek-v4-flash。

8.2Claude Code, directlyClaude Code，直連

ds4-server supports Anthropic’s /v1/messages natively. The header of ds4_server.c describes it as an "OpenAI/Anthropic compatible local server". Claude Code needs no router or proxy. Set three environment variables, then start it:

ds4-server 原生支援 Anthropic 的 /v1/messages。ds4_server.c 檔案開頭自稱是 "OpenAI/Anthropic compatible local server"。Claude Code 不需要 router 或 proxy。設好三個環境變數後再啟動：

export ANTHROPIC_BASE_URL=http://127.0.0.1:8000
export ANTHROPIC_AUTH_TOKEN=sk-local   # any string; ds4-server does not check it任意字串，ds4-server 不檢查
export ANTHROPIC_MODEL=deepseek-v4-flash

claude

Your slash commands, subagents and MCP servers stay the same. Only the model underneath changes. Be honest with yourself about what else changes with it. This model’s tool-calling training is weaker than Claude’s, so it slips more often in long tool loops. It works best for long conversations, writing and explaining code. You will notice the difference in a workflow built from many tool calls.

你的 slash command、subagent 和 MCP server 都會保留，只有底下的模型換掉。也請老實面對一件事：換掉的不只是模型。這顆模型的工具呼叫訓練不如 Claude，在很長的工具迴圈裡比較常出錯。它最擅長長對話、寫作和解釋程式碼。如果你的工作流程是一個工具接著一個工具一路呼叫，就會感覺到差別。

8.3OpenClawOpenClaw

OpenClaw has two good options. For normal text turns, point its provider directly at the Responses endpoint. To keep the Codex runtime’s plugins and Computer Use, use the Codex-harness setup below. It configures two layers, not one.

OpenClaw 有兩種好用的做法。一般文字對話時，直接把 provider 指到 Responses 端點。若想保留 Codex runtime 的 plugin 和 Computer Use，請用下面的 Codex harness 設定。它要設兩層，不是一層。

{
  "agents": { "defaults": { "model": { "primary": "ds4/deepseek-v4-flash", "fallbacks": [] } } },
  "models": {
    "mode": "merge",
    "providers": {
      "ds4": {
        "baseUrl": "http://127.0.0.1:8000/v1",
        "apiKey": "sk-local",
        "api": "openai-responses",
        "timeoutSeconds": 600,
        "models": [{
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4.1 Flash (local Responses)",
          "api": "openai-responses",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 64000
        }]
      }
    }
  }
}

contextWindow must not exceed ds4-server’s --ctx, which defaults to 128000. Otherwise OpenClaw sends a prompt that is too long and the server rejects it. Write the full provider block at once. Setting keys one at a time with openclaw config set … often misses models[], agents.defaults.model.primary or api, and the session then quietly stays on the old provider.

contextWindow 不能超過 ds4-server 的 --ctx，預設是 128000。超過的話，OpenClaw 會送出太長的 prompt，伺服器會拒絕。請一次寫完整段 provider 設定。用 openclaw config set … 一個個設 key，常會漏掉 models[]、agents.defaults.model.primary 或 api，結果對話會默默繼續用舊的 provider。

{
  "agents": {
    "defaults": {
      "model": { "primary": "ds4-local/deepseek-v4-flash", "fallbacks": [] },
      "agentRuntime": { "id": "codex", "fallback": "none" }
    }
  },
  "plugins": {
    "entries": {
      "codex": {
        "enabled": true,
        "config": {
          "appServer": {
            "command": "/usr/local/bin/codex",
            "transport": "stdio",
            "approvalPolicy": "never",
            "sandbox": "danger-full-access"
          },
          "computerUse": { "enabled": true, "autoInstall": true }
        }
      }
    }
  },
  "models": {
    "providers": {
      "ds4-local": {
        "baseUrl": "http://api-proxy:1234/v1",
        "apiKey": "dsv4-local",
        "api": "openai-responses",
        "models": [{
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4.1 Flash (ds4.c local)",
          "api": "openai-responses",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 64000
        }]
      }
    }
  }
}

model = "deepseek-v4-flash"
model_provider = "ds4-local"
model_context_window = 100000
model_auto_compact_token_limit = 90000
model_reasoning_effort = "high"

[model_providers.ds4-local]
name = "ds4-local"
base_url = "http://api-proxy:1234/v1"
env_key = "DS4_API_KEY"
wire_api = "responses"
requires_openai_auth = false

[plugins."computer-use@openai-bundled"]
enabled = true

If OpenClaw runs in Docker or OrbStack, its 127.0.0.1 is the container itself. Use host.docker.internal:8000, or a passthrough api-proxy as in the example, so http://api-proxy:1234/v1 forwards to the host’s http://127.0.0.1:8000/v1. The first Codex-harness turn often has a tool prompt of 50,000 tokens or more. ds4-server’s disk KV cache (§6.4) makes retries and nearby sessions much faster. If you enable steering on this path, keep the V4-calibrated FFN-only settings: DS4_DIR_STEERING_FFN=-0.75 and DS4_DIR_STEERING_ATTN=0. The older ffn=-2, attn=-0.5 acid-test setting can make steering leak into DSML and tool-call syntax with prompts this long.

若 OpenClaw 跑在 Docker 或 OrbStack 裡，容器內的 127.0.0.1 指的是容器自己。請用 host.docker.internal:8000，也可以像範例一樣加一個直通的 api-proxy，讓 http://api-proxy:1234/v1 轉送到主機的 http://127.0.0.1:8000/v1。Codex harness 的第一個回合常有 50,000 個 token 以上的工具 prompt，ds4-server 的磁碟 KV cache（§6.4）會讓重試和相近的對話快很多。若你在這條路上開啟引導，請保留在 V4 上校準的 FFN-only 設定：DS4_DIR_STEERING_FFN=-0.75、DS4_DIR_STEERING_ATTN=0。舊的 ffn=-2, attn=-0.5 壓力測試設定，遇到這麼長的 prompt 時，可能會滲進 DSML 和工具呼叫的語法裡。

8.4Hermes AgentHermes Agent

The quickest option is interactive. Run hermes model, choose “Custom endpoint (self-hosted / VLLM / etc.)” and enter http://127.0.0.1:8000/v1. To save it in the config instead:

最快的方法是互動設定。執行 hermes model，選「Custom endpoint (self-hosted / VLLM / etc.)」，再輸入 http://127.0.0.1:8000/v1。若想存進設定檔：

custom_providers:
  - name: ds4
    base_url: http://127.0.0.1:8000/v1
    # api_key omitted: the local server does not check itapi_key 省略：本機伺服器不檢查

model:
  default: deepseek-v4-flash
  provider: custom:ds4

In a session, run /model custom:ds4:deepseek-v4-flash to switch at any time.

在對話中，隨時可用 /model custom:ds4:deepseek-v4-flash 切換。

8.5Straight to the API: the OpenAI SDK, curl, your own scripts直接打 API：OpenAI SDK、curl、自己的腳本

The setups above all use the same base URL and an unchecked key. If you have a pipeline, a cron job or code written for the OpenAI SDK, set OPENAI_BASE_URL or pass base_url. Nothing else changes:

上面每種做法都只靠同一個 base URL 和一把不會被檢查的金鑰。若你有 pipeline、cron job，或已經用 OpenAI SDK 寫好程式，只要設定 OPENAI_BASE_URL 或傳入 base_url。其他地方不用改：

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="sk-local",   # any value任意值
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "自我介紹"}],
)
print(resp.choices[0].message.content)

If your pipeline already uses the Responses API that Codex CLI uses, client.responses.create() reaches the same server:

如果你的 pipeline 已經用 Codex CLI 那套 Responses API，client.responses.create() 也是連到同一台伺服器：

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="sk-local",
)

resp = client.responses.create(
    model="deepseek-v4-flash",
    input=[{"role": "user", "content": "自我介紹"}],
)
print(resp.output_text)

8.6When does ds4-server run?ds4-server 什麼時候在跑？

The lease and watchdog in Chapter 7 only see pi. They start the server when a pi process sends a model request. They stop it about a minute after the last pi process exits. If you never open pi (say you live in Codex CLI all day), start the server another way. These three options mainly differ in who runs the process.

第七章的租約和看門狗只看得到 pi。pi 程序透過模型發出請求時，它們會啟動伺服器。最後一個 pi 程序結束約一分鐘後，它們會把伺服器停掉。若你根本不開 pi，例如整天都用 Codex CLI，就要用別的方法啟動伺服器。下面有三種做法，主要差在誰來管理這個程序。

A. pi is installed: let pi keep it aliveA. 裝了 pi，讓 pi 替你顧著

Keep one pi session open and select the ds4 model once. Its lease renews every ten seconds. The watchdog sees an active client, so the server stays up while that window is open. You need no setup, only one terminal tab.

開著一個 pi 視窗，再選一次 ds4 模型就好。它每十秒更新一次租約。看門狗看到還有客戶端在用，伺服器就會跟著那個視窗持續執行。不用再設定，只是會多占一個終端機分頁。

B. pi is installed: run the server by handB. 裝了 pi，自己手動跑伺服器

The checkout in ~/.pi/ds4/support already contains a built binary and the weights. Here is the managed launch written out:

~/.pi/ds4/support 裡的 checkout 已經有編好的執行檔和權重。以下把代管啟動指令完整列出：

cd ~/.pi/ds4/support
./ds4-server \
  --ctx 128000 \
  --kv-disk-dir ~/.pi/ds4/kv \
  --kv-disk-space-mb 65536 \
  --vision gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf
# 65536 is the default on a 128 GB Mac.65536 是 128 GB 的 Mac 的預設值。
# Drop --vision for a text-only server. Engine-level flags from the只要純文字就拿掉 --vision。更新誌裡的引擎級旗標
# What's-new list (--ssd-streaming, --mtp DSpark.gguf, --max-queue N) go here.（--ssd-streaming、--mtp DSpark.gguf、--max-queue N）就加在這裡。

To enable steering on a hand-started server, add the four flags the managed path would use, with a direction file of your own for V4.1 (the −0.75 is the V4 measurement):

若要在手動啟動的伺服器開啟引導，加上代管路徑會用的四個旗標，方向檔請用你自己為 V4.1 建的（−0.75 是 V4 的實測值）：

cd ~/.pi/ds4/support
./ds4-server \
  --ctx 128000 \
  --kv-disk-dir ~/.pi/ds4/kv \
  --kv-disk-space-mb 65536 \
  --vision gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf \
  --dir-steering-file dir-steering/out/candor-v41.f32 \
  --dir-steering-ffn 1 \
  --dir-steering-attn 0

pi adopts a server already listening on 127.0.0.1:8000. The adopted server keeps exactly the flags you gave it. pi does not add --ctx or steering again. That is deliberate. You can audit a command you typed. It also means you must add the vision sidecar, KV disk cache or steering yourself when you start the server by hand.

pi 會「收養」已經在 127.0.0.1:8000 監聽的伺服器。被收養的伺服器只保留你啟動時給的旗標，pi 不會再補 --ctx 或引導。這是刻意的設計，不是少了功能。你親手輸入的啟動指令，就能自己檢查。這也表示，若手動啟動時要視覺附屬檔、KV 磁碟快取或引導，必須自己加上。

C. No pi at allC. 完全沒有 pi

Bootstrap directly from the two repositories. You need neither pi nor ~/.pi/ds4/. Both repositories matter. ds4’s download_model.sh fetches antirez’s upstream stock recipe. The identically named script in pi-kami fetches the V4.1 Maya-XS pair covered by this letter.

直接從兩個 repo 開始。不需要 pi，也不需要 ~/.pi/ds4/。需要兩個 repo 是因為 ds4 裡的 download_model.sh 會抓 antirez 上游的原版配方。pi-kami 裡同名的腳本，才會抓這封信談的 V4.1 Maya-XS 一對檔案。

# 1. Fetch and build the engine at this release’s pin (Metal only for this model, see §8.7)1. 取得並依這個版本的釘版編譯引擎（這顆模型只走 Metal，見 §8.7）
git clone https://github.com/audreyt/ds4
cd ds4
git checkout 0dff39f91721bcf3472813c6d2bebf9353df2a1a
make ds4-server

# 2. The V4.1 Maya-XS download script from pi-kami, not ds4's own stock-recipe one2. 用 pi-kami 的 V4.1 Maya-XS 下載腳本，不是 ds4 自帶的原版配方那支
curl -fL -o download_model.sh \
  https://raw.githubusercontent.com/audreyt/pi-kami/main/download_model.sh
chmod +x download_model.sh
./download_model.sh q1
# fetches the ~341.5 GiB language GGUF plus the vision sidecar and links ds4flash.gguf抓約 341.5 GiB 的語言 GGUF 與視覺附屬檔，並連結為 ds4flash.gguf

# 3. Start the server (append the four steering flags from path B to opt in)3. 啟動伺服器（要開引導，把 B 路線的四個旗標接在後面）
./ds4-server \
  --ctx 128000 \
  --kv-disk-dir ./kv \
  --kv-disk-space-mb 65536 \
  --vision gguf/DeepSeek-V4.1-Flash-1017-Vision.gguf

With this option, you never use pi. ds4-server comes directly from the source tree. You handle the jobs the extension would otherwise do: downloading, symlinks, the watchdog and leases.

走這條路完全不用 pi。ds4-server 直接從原始碼樹執行。擴充套件原本會做的下載、symlink、看門狗和租約，都要在需要時自己處理。

8.7Other hardware: DGX Spark (CUDA) and Strix Halo (ROCm)其他硬體：DGX Spark（CUDA）與 Strix Halo（ROCm）

The ds4 tier needs a Mac with 128 GB and Metal. ds4 runs this model’s IQ1_S experts only on Metal, so pi-kami refuses a Linux host with CUDA or ROCm, such as an NVIDIA DGX Spark or an AMD Strix Halo, before it downloads anything. Those hosts should stay on v 0.6.1, which runs the V4 Vision-Exp IQ2 build as that release describes. Or bring your own: point DS4_RUNTIME_DIR at your own ds4 checkout and binary, and supply a GGUF your backend can run. Macs under 128 GB have two paths. An M4 Pro, M5 Pro or M5 Max with 48 GB or more can choose rec/flint (§1.1a). Other Macs should stay on v 0.6.1.

ds4 這一層需要 128 GB 的 Mac，而且要走 Metal。ds4 只在 Metal 上執行這個模型的 IQ1_S 專家，所以 pi-kami 會在下載任何東西之前，就拒絕 Linux 上用 CUDA 或 ROCm 的主機（NVIDIA DGX Spark、AMD Strix Halo）。這些主機請留在 v 0.6.1，照該版本的說明跑 V4 Vision-Exp IQ2。或者自備：把 DS4_RUNTIME_DIR 指向你自己的 ds4 checkout 與執行檔，再提供你的後端跑得動的 GGUF。不到 128 GB 的 Mac 有兩條路：48 GB 以上的 M4 Pro、M5 Pro 或 M5 Max 可以選 rec/flint（§1.1a），其他 Mac 請留在 v 0.6.1。

The rest of this section describes the engine, for v 0.6.1 or your own GGUF. Since the 2026-07 pin, there is a third backend: AMD Strix Halo on ROCm. A 128 GB Ryzen AI Max machine with Radeon 8060S and gfx1151 builds the same binaries with make strix-halo, also called make rocm. The checkout’s STRIXHALO.md covers ROCm 7.1, rocWMMA, /dev/kfd permissions and the GTT aperture. On this platform, use the plain aligned-imatrix GGUF. For now, avoid mixed IQ2/Q4 builds. They add much more memory pressure to the ROCm path and may end in a system out-of-memory (OOM) error instead of a clean ds4 error. The same pin added distributed inference: 4-bit Flash runs across two 128 GB MacBooks over Thunderbolt 5, with each mapping only its own layers. Pipelined prefill (reading the prompt in a relay across both machines) can beat one machine, but generation is slower.

這一節其餘部分談的是引擎本身，適用於 v 0.6.1 或你自備的 GGUF。2026-07 釘版加入了第三個後端：ROCm 上的 AMD Strix Halo。128 GB 的 Ryzen AI Max 機器，搭配 Radeon 8060S 和 gfx1151，可用 make strix-halo 編出同一組執行檔。它也叫 make rocm。checkout 裡的 STRIXHALO.md 說明 ROCm 7.1、rocWMMA、/dev/kfd 權限和 GTT aperture。這個平台請用單純的 aligned-imatrix GGUF。暫時先避開 IQ2/Q4 混合版。它在 ROCm 路徑上的記憶體壓力大得多，結果可能是整台系統記憶體不足（OOM），而不是 ds4 給出的明確錯誤訊息。同一份釘版也加入分散式推論：4-bit Flash 可透過 Thunderbolt 5 跨兩台 128 GB MacBook 執行，每台只 map 自己負責的那幾層 layer。管線化的 prefill（兩台接力讀完整段提示）可能比單機快，但生成較慢。

Once the endpoint is running, use the §8.1 to §8.5 setups as written. If you connect from another machine, replace 127.0.0.1 with its address. Two things to know:

端點啟動後，§8.1 到 §8.5 的設定可以照用。若從另一台機器連線，請把 127.0.0.1 改成那台機器的位址。不過有兩點要知道：

• Opening it to a LAN is your responsibility. ds4-server binds 127.0.0.1 and checks no key. To use it across machines, put it behind Tailscale or an authenticated reverse proxy. Do not change --host to 0.0.0.0 and expose an unauthenticated model to the network.
• The watchdog and leases work on Linux. ds4-watchdog.sh handles BSD and GNU userlands, including stat -f %m and stat -c %Y, plus LC_ALL=C ps -o lstart. Chapter 7’s lifecycle therefore works on Linux too, for v 0.6.1 or your own binary. You can still run ./ds4-server by hand, or use a systemd unit or tmux session, if you prefer no automation.

• 開放到區網要由你負責。ds4-server 綁在 127.0.0.1，也不檢查金鑰。跨機器使用時，請放在 Tailscale 或有驗證的 reverse proxy 後面。不要把 --host 改成 0.0.0.0，讓沒有驗證的模型直接暴露在網路上。
• 看門狗和租約也能在 Linux 執行。ds4-watchdog.sh 同時處理 BSD 和 GNU 工具，包含 stat -f %m 對應 stat -c %Y，以及 LC_ALL=C ps -o lstart。所以第七章的生命週期在 Linux 上也能用，適用於 v 0.6.1 或你自備的執行檔。若不想用自動化，也能手動執行 ./ds4-server，或用 systemd unit、tmux 視窗。

Everything but the weights is the same across platforms: one engine, one startup shape, one ds4-watchdog.sh. What v 0.7 changes is the model, and that model needs Metal.

除了權重，各平台都一樣：同一個引擎、同一種啟動方式、同一份 ds4-watchdog.sh。v 0.7 改變的是模型，而這顆模型需要 Metal。

Troubleshooting: leases and the watchdog故障排除：租約與看門狗

The extension keeps all of its working state as plain files under ~/.pi/ds4/. This is on purpose. When something feels wrong, you can read the files and see what the extension thinks is going on. You shouldn’t need to open the source code.

擴充套件把執行時的所有狀態，都存成一般的檔案，放在 ~/.pi/ds4/ 底下。這是刻意的設計。覺得哪裡不對勁時，你只要讀這些檔案，就知道擴充套件現在以為發生了什麼事。不用打開原始碼。

9.1What lives where什麼東西放在哪裡

9.2Symptoms, and what to do about them症狀，以及怎麼處理

“The server has been starting for more than ten minutes”「伺服器啟動中已經超過十分鐘」

Read the last few hundred lines of log. With the model on an internal SSD, ten minutes is rarely about disk speed. More often the GGUF (the model file) sits on a slow external drive, or another startup step is stuck. Check the log first. Raise DS4_READY_TIMEOUT_MS only if you have a real reason to wait longer.

先讀 log 的最後幾百行。模型放在內建 SSD 上時，等上十分鐘通常不是磁碟太慢。比較常見的原因，是 GGUF（模型檔）放在很慢的外接硬碟上，或是啟動的某個步驟卡住了。先看 log 找原因。只有你確定有理由多等一下，才把 DS4_READY_TIMEOUT_MS 調大。

“pi says ds4-server startup failed”「pi 說 ds4-server startup failed」

The log names the cause. It’s usually one of three things: make ds4-server failed (missing Xcode command-line tools?), the GGUF download broke (network? disk full?) or the current build rejected a ds4-server flag you added by hand.

log 會寫出失敗的原因，通常是這三種之一：make ds4-server 失敗了（是不是沒裝 Xcode 命令列工具？）、GGUF 下載中斷了（網路斷了？硬碟滿了？），或是你手動加的某個 ds4-server 參數，目前這個版本不接受。

“/ds4-agent says the server is in use”「/ds4-agent 說伺服器正在使用中」

This is a safety guard, not a fault. The native agent has to load its own copy of the same model. If another pi window or HTTP client is still using ds4-server, the extension says no, so it won’t cut someone off mid-request. Wait for those requests to finish, close the other pi windows or clear old leases with the gentle restart below. Then try again.

這是保護機制，不是故障。原生智慧體得自己載入同一個模型。如果還有別的 pi 視窗或 HTTP 用戶端在用 ds4-server，擴充套件會拒絕，免得把別人的請求中途打斷。你可以等那些請求跑完、關掉其他 pi 視窗，或用下面的溫和重啟，清掉過期的租約（lease，也就是「我還在用」的登記檔）。然後再試一次。

“I want to restart everything”「我想把一切重啟」

Try the gentle way first. Empty ~/.pi/ds4/clients/. About two seconds later the watchdog (a small background check that stops the server when nobody is using it) looks again, sees no leases and shuts the server down cleanly.

先試溫和的辦法。把 ~/.pi/ds4/clients/ 清空。大約兩秒後，看門狗（一個在背景檢查、沒人用就關掉伺服器的小程式）再檢查一次，發現沒有租約，就會乾淨地關掉伺服器。

# Clear every lease; the watchdog stops the server on its next poll.清掉所有租約，看門狗下一輪巡查就會停掉伺服器。
# find -delete rather than rm with a glob, so zsh stays quiet on an empty directory.用 find -delete 而不是 rm 加萬用字元，空目錄時 zsh 才不會報錯。
find ~/.pi/ds4/clients -maxdepth 1 -name '*.json' -delete 2>/dev/null || true

# Print the key fields of server.json and the matching process's arguments and start time:印出 server.json 的關鍵欄位，以及對應程序的參數與啟動時間：
STATE=~/.pi/ds4/server.json
if [ ! -f "$STATE" ]; then
  echo 'no server.json (already clean)'
else
  MANAGED=$(sed -n 's/.*"managedBy"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$STATE" | head -1)
  PID=$(sed -n 's/.*"pid"[[:space:]]*:[[:space:]]*\([0-9]*\).*/\1/p' "$STATE" | head -1)
  BINARY=$(sed -n 's/.*"binary"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$STATE" | head -1)
  echo "managedBy: $MANAGED"
  echo "pid:       ${PID:-<none>}"
  echo "binary:    ${BINARY:-<none>}"
  if [ -n "$PID" ] && kill -0 "$PID" 2>/dev/null; then
    ps -p "$PID" -o pid=,lstart=,args=
  else
    echo '(pid not running — state is stale, step 2 will clean it)'
  fi
fi

(
  STATE=~/.pi/ds4/server.json
  LOCKDIR=~/.pi/ds4/lock

  # mkdir as an atomic lock, the same mechanism index.ts uses; exit if it is held.用 mkdir 做原子鎖，與 index.ts 同一套機制。鎖被別人持有時就退出。
  if ! mkdir "$LOCKDIR" 2>/dev/null; then
    echo "abort: lock $LOCKDIR is held; owner:"
    cat "$LOCKDIR/owner.json" 2>/dev/null || echo '(no owner.json — if > 60s old, rm -rf manually)'
    exit 1
  fi
  trap 'rm -rf "$LOCKDIR" 2>/dev/null' EXIT
  trap 'rm -rf "$LOCKDIR" 2>/dev/null; exit 130' INT
  trap 'rm -rf "$LOCKDIR" 2>/dev/null; exit 143' TERM
  trap 'rm -rf "$LOCKDIR" 2>/dev/null; exit 129' HUP

  if [ ! -f "$STATE" ]; then
    echo 'lifecycle already clean'; exit 0
  fi

  PID=$(sed -n 's/.*"pid"[[:space:]]*:[[:space:]]*\([0-9]*\).*/\1/p' "$STATE" | head -1)

  # Only touch state when the PID is gone, or absent from the state file.只有 PID 不存在（或狀態檔裡沒有 PID）時才動狀態。
  # If the PID is alive, refuse and hand off to step 3.PID 還活著就拒絕，交給第三步。
  if [ -n "$PID" ] && kill -0 "$PID" 2>/dev/null; then
    echo "refuse: pid $PID still alive."
    echo "        please verify via step 1 output, then use step 3 to kill manually."
    exit 2
  fi

  # The PID is dead or absent. Safe to clean.PID 已死或不存在。可以安全清理。
  find ~/.pi/ds4/clients -maxdepth 1 -name '*.json' -delete 2>/dev/null || true
  rm -f "$STATE"
  echo 'state cleared. lock will release on exit.'
)

# Replace PID_FROM_STEP_1_MUST_BE_REPLACED with the PID you confirmed by eye in step 1.把 PID_FROM_STEP_1_MUST_BE_REPLACED 換成你在第一步親眼確認過的那個 PID。
# The token is deliberately not a number: run unedited, this line only produces這個記號刻意不是數字：沒改就執行，這一行只會得到
# 'kill: arguments must be process or job IDs' and never sends a signal.'kill: arguments must be process or job IDs'，不會送出任何訊號。
kill -TERM PID_FROM_STEP_1_MUST_BE_REPLACED

# Give it a few seconds to exit cleanly, then run step 2 again to clear the state.給它幾秒鐘乾淨地退出，然後再跑一次第二步清掉狀態。

“The server is running but /v1/models does not answer”「伺服器在跑，但 /v1/models 沒有回應」

Check which program is using port 8000: lsof -nP -iTCP:8000 -sTCP:LISTEN. If another program has taken it, the server can’t start, and the log will say so.

查一下 8000 port 現在是誰在用：lsof -nP -iTCP:8000 -sTCP:LISTEN。如果被別的程式佔走了，伺服器就起不來，log 裡會寫。

Local development install本機開發安裝

Want to work on the engine, test your own patch or keep several ds4 forks side by side? Skip the pi install step. The bundled script links the extension and a ds4 checkout of your choice into place, using symlinks (shortcuts to a folder). So the code pi runs is the code open in your editor.

如果你想改引擎、測試自己的修補，或同時放好幾個 ds4 分叉，就別用 pi install。內附的腳本會用 symlink（資料夾的捷徑），把擴充套件和你指定的 ds4 checkout（下載好的原始碼）接到該放的位置。這樣 pi 執行的程式，就是你編輯器裡開著的那一份。

10.1Mounting a checkout掛上一個 checkout

./install-pi-extension-local.sh /path/to/audreyt-ds4-checkout

It does two things: it links ~/.pi/agent/extensions/pi-ds4 to the current pi-kami checkout, and links ~/.pi/ds4/support to the ds4 checkout you named.

它做兩件事：把 ~/.pi/agent/extensions/pi-ds4 連到目前的 pi-kami checkout，再把 ~/.pi/ds4/support 連到你指定的 ds4 checkout。

10.2When a support directory already exists: --forcesupport 目錄已經存在時：--force

If ~/.pi/ds4/support already points somewhere, say left over from an earlier pi install, the script won’t overwrite it. With --force it will:

若 ~/.pi/ds4/support 已經指向別的地方，例如上次 pi install 留下來的，腳本不會直接覆蓋。加上 --force 之後，它會：

• copy gguf/*.gguf and any .gguf.part from the old checkout into the new one with APFS clone-on-write (a copy that shares the original’s disk blocks). On macOS none of the 341.5 GiB actually moves, as the two paths share the same blocks.
• rename the old support directory to support.backup.<timestamp>.
• create the new symlink.

• 用 APFS 的 clone-on-write（複製時不真的複製資料），把舊 checkout 裡的 gguf/*.gguf 和 .gguf.part 複製到新的 checkout。在 macOS 上，341.5 GiB 不會真的搬動，兩個路徑共用同一批資料區塊。
• 把舊的 support 目錄改名為 support.backup.<timestamp>。
• 建立新的 symlink。

10.3Then reload然後重新載入

Restart pi, or run /reload inside it. pi will find the extension again at its new location.

重新啟動 pi，或在 pi 裡執行 /reload，它就會從新的位置重新找到擴充套件。

Building your own steering direction自己建一個引導方向

This chapter assumes you have read everything above, and it asks a different question. The bundled vector (a long list of numbers that points in one direction) expresses one preference: a contested question should open into a discussion. Yours may be different. It could be a tone of voice, a field of study, a way of hedging. The tools that built the bundled direction are in the checkout, and they can build yours too.

這一章假設你已經讀完前面的內容，要問的是另一個問題。內附的向量檔（一串指向某個方向的數字）代表一種偏好：有爭議的問題，應該展開成討論。你想要的可能不一樣，例如某種語氣、某個學科，或某種留餘地的說法。建出內附方向的那套工具就在 checkout 裡，也能拿來建你自己的。

A V4.1 direction is one f32 vector per layer at V4.1’s own width, 40 × 5120. The bundled V4 vectors (43 × 4096) cannot be reused, so from v 0.7 on, everything below starts from your own prompts.

V4.1 的方向，是每一層一個 f32 向量，寬度是 V4.1 自己的 40 × 5120。內附的 V4 向量（43 × 4096）不能沿用，所以在 v 0.7 裡，下面的一切都要從你自己的提示開始。

11.1Where the toolchain lives工具鏈在哪裡

Everything sits in dir-steering/ inside audreyt/ds4:

全部都在 audreyt/ds4 的 dir-steering/ 目錄裡：

• collect-acts.py runs the model over a set of paired, contrasting prompts (a forward pass) and records its hidden state at every layer;
• build-dir.py turns those activations (the model’s internal signals) into a direction, using PCA or simple subtraction, and writes a .f32 vector file;
• README.md is the full tutorial, with the design discussion behind the bundled vector.

• collect-acts.py 讓模型讀過一組成對的對比提示（前向計算），並記下每一層的隱藏狀態。
• build-dir.py 用 PCA（找出變化最大的方向）或相減的方式，把這些激勵值（模型內部的訊號）變成一個方向，寫成 .f32 向量檔。
• README.md 是完整教學，還有內附向量背後的設計說明。

11.2A typical workflow典型的工作流程

1. Write two sets of prompts: one that exhibits what you want to steer towards, one that exhibits what you want to steer away from. Fifty to two hundred of each is enough.
2. Run both sets through ds4-server with collect-acts.py to produce two sets of activations.
3. Let build-dir.py compute the layer-by-layer difference and write my-direction.f32.
4. Put the file under dir-steering/out/, or anywhere you like.
5. Point the extension at it:
   • DS4_DIR_STEERING_FILE=dir-steering/out/my-direction.f32
   • DS4_DIR_STEERING_FFN=-0.75, or whatever magnitude your own testing settles on
   • DS4_DIR_STEERING_ATTN=0: keep it at 0 whenever tools are in play
6. Restart ds4-server and test, first with the prompts you built from, then with prompts you did not.

1. 寫兩組提示：一組展現你想引導模型走向的樣子，一組展現你想讓它離開的樣子。每組五十到兩百條就夠。
2. 用 collect-acts.py 把兩組提示都交給 ds4-server，得到兩組激勵值。
3. 讓 build-dir.py 逐層算出兩組的差異，寫成 my-direction.f32。
4. 把檔案放到 dir-steering/out/，或任何你喜歡的位置。
5. 設定擴充套件去用它：
   • DS4_DIR_STEERING_FILE=dir-steering/out/my-direction.f32
   • DS4_DIR_STEERING_FFN=-0.75，或你自己測出來的強度
   • DS4_DIR_STEERING_ATTN=0：只要有用到工具，就維持 0
6. 重新啟動 ds4-server 測試：先用建向量時的那些提示，再用你沒用過的。

11.3Two principles for a direction worth keeping值得留下的方向，兩個原則

• Keep the contrast clean. The two sets should differ sharply along the one dimension you care about and resemble each other everywhere else. Build from “happy reply versus sad reply” and the direction you get carries a great deal more than mood.
• Steer style, not belief. Steering how the model answers (hedged or assertive, narrative or bulleted, academic or conversational) is far more reliable than steering what it concludes. That is why this fork built an uncertainty direction instead of a position. It is also why §4.3 exists.

• 對比要乾淨。兩組提示要在你在意的那一點上差很多，其他地方則盡量一樣。如果拿「快樂的回答」對「悲傷的回答」來建，得到的方向會混進很多別的東西，不只是情緒。
• 引導說話方式，不引導信念。引導模型怎麼回答（留餘地還是斬釘截鐵、敘事還是條列、學術還是口語），比引導它得出什麼結論可靠得多。這就是這個分叉建的是「不確定性」方向，而不是某個立場的原因。§4.3 會存在，也是同樣的道理。

For readers still deciding寫給還在猶豫的讀者

If you're still deciding whether to hand one of your machines to this model, here are the questions people ask most.

如果你還在猶豫，要不要讓自己的一台機器跑這顆模型，下面是大家最常問的問題。

Terms, cross-referenced名詞對照

These words come up again and again in this letter, and they may be new if you work outside engineering. If they're old friends, skip ahead.

這封信裡一再出現的詞，如果你不是工程背景，可能有些陌生。都已經認識的話，就往後跳吧。

Model and weights模型與權重

parameter參數

A number inside a neural network that gets adjusted during training. More parameters roughly means the model can hold more. This letter quotes no total for V4.1 Flash, as no verified figure exists.

神經網路裡的一個數字，訓練時會不斷調整它。參數越多，大致上模型能裝的東西越多。這封信沒有引用 V4.1 Flash 的總數，因為沒有可靠的數字。

MoE混合專家

Mixture of Experts. The model is split into many small expert networks, but each token wakes only a few, here 6 of 384 routed experts plus one shared expert. It does the arithmetic of a much smaller model while carrying the knowledge of a large one.

Mixture of Experts。模型分成許多小型專家網路，每個 token（模型讀寫文字的單位）只會喚醒其中幾個，這裡是 384 個路由專家中的 6 個，外加一個共用專家。它做的運算像一顆小得多的模型，卻裝著大模型的知識。

quantization量化

Quantisation squeezes weights into fewer bits so the model takes less space. The earlier V4.1 Q1 mixed formats: routed experts (the specialist parts chosen for each token) were IQ1_S, the dense path was mostly Q6_K and Q5_K and the attention output projections stayed at Q8_0. Maya-XS is a ds4-native GGUF (§3.3). The language GGUF is 365713686528 bytes, plus a 970555552-byte vision sidecar.

量化把權重壓成較少的位元，讓模型佔用更少空間。先前的 V4.1 Q1 混用多種格式：路由專家（每個 token 選出的專門部分）是 IQ1_S，稠密路徑多為 Q6_K 與 Q5_K，注意力的輸出投影保留 Q8_0。Maya-XS 是 ds4 原生 GGUF（§3.3）。語言 GGUF 共 365713686528 位元組，另有 970555552 位元組的視覺附屬檔。

GGUF模型檔格式

The single-file model format of the llama.cpp family (.gguf). The weights, the model's structure and its tokenizer (the part that cuts text into tokens) all sit in one file. The language GGUF here is 365713686528 bytes.

llama.cpp 這一系列工具用的單檔模型格式（.gguf）。權重、模型結構和 tokenizer（把文字切成 token 的部分），都放在同一個檔案裡。這裡的語言 GGUF 是 365713686528 位元組。

Engram tablesEngram 查找表

Lookup tables that V4.1 adds next to its experts. The model reads only a few rows of them per token, so ds4 leaves them on disk: about 189 GiB in two tables. An internal SSD matters for that reason (§3.1).

V4.1 在專家旁邊多出來的查找表。模型每個 token 只讀其中幾列，所以 ds4 把它們留在硬碟上：兩張共約 189 GiB。內建 SSD 因此很重要（§3.1）。

IQ1_SIQ1_S 格式

A very low-bit quantisation format, used here for the routed experts. ds4 has supported it on Metal since the d3f4cd6 pin (§3.3).

非常低位元的量化格式，這裡用在路由專家上。從 d3f4cd6 這個釘版起，ds4 在 Metal 上能跑它（§3.3）。

imatrix重要性矩陣

A calibration file recording which weights matter most for the model’s output. The quantiser spends its bits there first.

一份校準檔，記錄哪些權重對模型的輸出最重要。量化器會先把位元花在那些地方。

vision sidecar視覺附屬檔

A companion file that carries the part of the model that reads images, kept apart from the language weights (§3.4).

帶著讀圖片那一部分模型的配套檔案，和語言權重分開存放（§3.4）。

abliteration拒絕方向消除

Finding the direction inside the model that triggers "refuse to answer", then subtracting it while the model computes. This loosens over-refusal. It's neither a jailbreak nor a safety guarantee (§3.2).

找出模型內部觸發「拒絕回答」的那個方向，在模型運算時把它減掉。這能減少不必要的拒答。它不是越獄，也不是安全保證（§3.2）。

Inference and hardware推論與硬體

token詞元

The unit a model reads and writes in. A Chinese character is roughly one to three tokens. An English word is one or two.

模型讀寫文字的基本單位。一個漢字約是一到三個 token，一個英文單字約是一到兩個。

prefill / decode預填／逐字生成

The two stages of inference, when the model produces an answer. Prefill reads the whole prompt in one go, while decode writes the reply one token at a time. In a long conversation, decode is the part you feel: it runs for every new token.

推論（模型產生回答）分成兩個階段。Prefill 一口氣讀完整段提示，decode 則一個 token 一個 token 地寫出回覆。長對話裡你感覺得到的是 decode，因為每個新 token 都要跑一次。

context window上下文視窗

How many tokens the model can see at once. The official window is 1M. This extension opens 128k by default, and a 128 GB Mac refuses any window of 512k or more (§6.4). The abliterated weights haven’t been validated beyond 32k, so treat anything above that as experimental.

模型一次能看到多少 token。官方的視窗是 1M。這個擴充套件預設開 128k，128 GB 的 Mac 會拒絕 512k 以上（§6.4）。abliterated 權重在 32k 以上沒有驗證過，超過的部分請當作實驗。

KV cache鍵值快取

The model's short-term memory during inference, which saves intermediate results so earlier tokens do not need recomputing. Long conversations create a lot of it, and this extension lets it spill onto disk. When DS4_KV_DISK_SPACE_MB is unset, it is about 64 GB on a 128 GB Mac.

模型在推論時使用的短期記憶，會存下中間結果，讓先前的 token 不必重算。長對話會累積很多，本擴充套件允許它溢出到硬碟。DS4_KV_DISK_SPACE_MB 沒設定時，128 GB 的 Mac 約 64 GB。

unified memory統一記憶體

On Apple Silicon, the CPU and GPU share one pool of RAM. Nothing needs copying into separate video memory (VRAM). That's why a Mac can hold a model this size at all.

Apple Silicon 的 CPU 和 GPU 共用同一塊 RAM，不必再把資料複製到另一塊顯示記憶體（VRAM）。Mac 能裝下這麼大的模型，靠的就是這一點。

Metal 4 / Metal TensorApple 的 GPU 介面

Metal is Apple's programming interface for the GPU, and Metal 4 adds tensor APIs (tools for working with big arrays of numbers). pi-kami doesn't pick a backend profile in its wrapper. The ds4 build decides which path is actually used.

Metal 是 Apple 讓程式使用 GPU 的介面，Metal 4 加入了 tensor API（處理大量數字陣列的工具）。pi-kami 的包裝層不挑後端設定，實際走哪條路，由 ds4 的建置決定。

SSD streamingexperts streamed from diskSSD 串流

The engine's capacity mode (--ssd-streaming). Non-routed weights stay in memory, while routed experts live in an in-memory cache and are read back from the GGUF when missing, letting a model larger than your RAM run but slowing decode at every miss. The managed path does not pass this flag. See What’s new and §8.6.

引擎的容量模式（--ssd-streaming）。非路由權重常駐記憶體，路由專家則放在記憶體快取裡，未命中時才從 SSD 上的 GGUF 讀回，讓比 RAM 還大的模型也能跑，代價是每次未命中都會拖慢 decode。代管路徑不會傳這個旗標，詳見 更新誌 與 §8.6。

speculative decoding / DSpark推測解碼

A small draft head guesses a block of tokens ahead, and the full model checks them before keeping any. ds4 turns it on with --mtp DSpark.gguf (experimental). This fork adds B2 rejection sampling, so the output is statistically identical to plain decoding, with nothing lost. The V4.1 Maya-XS does not use it: the drafter does not fit beside it on 128 GB.

先由一個小的草稿頭一次猜一整段 token，完整模型檢查過才採用。ds4 用 --mtp DSpark.gguf 開啟（實驗性）。這個分叉加了 B2 rejection sampling，輸出的機率分佈和不開推測時完全一樣，沒有任何損失。V4.1 Maya-XS 不用它：128 GB 裡，草稿頭放不進它旁邊。

Directional steering and this fork方向性引導與這個分叉

directional steering方向性引導

While the model runs, it gives the internal signals (activations) at chosen layers a small push, towards or away from a trait that a direction vector stands for. No retraining is involved (Chapter 4).

模型執行時，在選定的層輕輕推一下內部的訊號（激勵值），推向或推離某個方向向量所代表的特質。不需要重新訓練（第四章）。

FFN / attention前饋／注意力

The two main blocks of computation inside each Transformer layer. This fork’s V4 setting steers only the FFN output (ffn=-0.75) and leaves attention alone (attn=0), so the syntax of tool calls isn't disturbed.

Transformer 每一層裡兩個主要的運算區塊。這個分叉在 V4 上的開啟方式，只引導 FFN 的輸出（ffn=-0.75），不動注意力層（attn=0），這樣工具呼叫的格式就不會被干擾。

uncertainty direction不確定性方向

The vector shipped with this fork. It was built from 120 contested prompts, half English and half Traditional Chinese, with Taiwan and Hong Kong deliberately left out. It contrasts fairly laying out each side's stake with giving a single answer. It was built for V4, and V4.1 needs its own.

這個分叉附的向量，用 120 條有爭議的提示建成，英文和繁體中文各一半，刻意不放台灣與香港。它對比兩種回答框架：公平呈現各方利害關係，或直接給單一答案。它是為 V4 建的，V4.1 需要自己的方向。

response register回應語體

How a reply is delivered rather than what it says: hedged or flat-out, bulleted or story-like, academic or chatty. This is much easier to steer than a stance.

回答的方式，不是回答的內容：留餘地還是斬釘截鐵，條列還是說故事，學術還是口語。這比立場容易引導得多。

System and lifecycle系統與生命週期

ds4-serverHTTP 推論伺服器

The inference server that runs in the background. pi and other HTTP clients talk to it. It listens on 127.0.0.1:8000, and leases and the watchdog decide how long it lives.

在背景執行的推論伺服器，pi 和其他 HTTP 客戶端都跟它對話。它在 127.0.0.1:8000 等連線，什麼時候關掉，由租約和看門狗決定。

ds4-agent原生終端機 agent

The terminal agent built into the ds4 checkout, not a server. It controls the terminal, its own session and KV state and its own DSML tool loop. pi-kami reaches it through the foreground handoff /ds4-agent.

ds4 checkout 內建的終端機智慧體，不是伺服器。終端機、對話、KV 狀態，還有它自己的 DSML 工具迴圈，全由它掌管。pi-kami 用前景交接 /ds4-agent 進入它。

lease租約

A small file that says "I'm still here". Each pi process using ds4 writes one to ~/.pi/ds4/clients/<pid>.json and refreshes it every ten seconds.

一個表示「我還在」的小檔案。每個使用 ds4 的 pi 程序，都會寫一份到 ~/.pi/ds4/clients/<pid>.json，每十秒更新一次。

watchdog看門狗

A small shell script that keeps running. Every two seconds it checks the leases, and when none is valid, it shuts ds4-server down.

一支常駐的小 shell script。它每兩秒檢查一次租約，沒有任何有效租約時，就把 ds4-server 關掉。

system prompt系統提示

The role and rules you give the model before a conversation starts. This fork's uncertainty steering works together with a prompt that asks for stakeholder framing (§4.5). Neither replaces the other.

對話開始前，先交給模型的角色與規則。這個分叉的不確定性引導，要搭配一段要求呈現各方立場的提示才有效（§4.5）。兩者不能互相取代。

/health · /stats狀態端點

Read-only endpoints on ds4-server, available since the 2026-07 pin. /health says whether the server is alive and for how long. /stats reports queue depth, cache hits per source and the speeds of the last prefill and decode. Both answer even in the middle of a generation (§7.1).

ds4-server 上的唯讀端點，從 2026-07 的釘版起提供。/health 回報伺服器是否活著、跑了多久。/stats 回報佇列深度、各來源的快取命中數，以及最近一次 prefill 與 decode 的速度。就算正在生成回答，兩個也都會回應（§7.1）。

Thanks, licence, afterword致謝、授權、後話

Thanks致謝

• mitsuhiko/pi-ds4, the upstream this extension is forked from. Armin Ronacher wrote the whole lifecycle: the leases, the watchdog, the lock. He wrote it so that people could read it.
• antirez/ds4, Salvatore Sanfilippo's DeepSeek V4 and V4.1 Flash engine, written in plain C in the same spirit as Redis. The V4 GGUF conversion came from its sibling project, llama.cpp-deepseek-v4-flash. V4.1 files are built with ds4’s own gguf-tools.
• The ds4 runtime and backend contributors. SSD streaming, distributed inference and the ROCm integration were led by antirez. Others: elkaix (server observability and the agent-loop cache, PR #489), MA (DSpark B2 rejection sampling), Nick Parrin (Strix Halo), Andrea Borio (mixed-quant expert streaming), rinaldofesta (the eval grader), kamranjon and fry69 (agent fixes), Andreas Spannagel (the MTP verify fix) and ivanfioravanti (M5 Metal 4 / MPP). pi-kami only packages that runtime and adds no tuning of its own.
• Project Maya by Peasant Smith: the IQ1_S experts and Q8 tensors in the Maya-XS build.
• kernelpool/ds4 and Ivan Fioravanti, whose V4.1 Metal work is merged into the pinned engine.
• The cyberneurova research project, whose abliterated GGUF first made running DeepSeek V4 Flash at home a real option.

• mitsuhiko/pi-ds4，本擴充套件分叉自它。Armin Ronacher 寫了整套生命週期管理，包括租約、看門狗和鎖，而且寫得讓人讀得懂。
• antirez/ds4，Salvatore Sanfilippo 用純 C 寫的 DeepSeek V4 與 V4.1 Flash 引擎，和他寫 Redis 時一脈相承。V4 的 GGUF 轉換來自它的姊妹專案 llama.cpp-deepseek-v4-flash，V4.1 的檔案則用 ds4 自己的 gguf-tools 做出來。
• ds4 執行期與後端的貢獻者。SSD 串流、分散式推論和 ROCm 整合，由 antirez 主導。其他貢獻者有：elkaix（伺服器可觀測性與智慧體迴圈快取，PR #489）、MA（DSpark B2 rejection sampling 與自適應區塊）、Nick Parrin（移植到 Strix Halo）、Andrea Borio（混合量化的專家串流）、rinaldofesta（評分器修正）、kamranjon 與 fry69（智慧體的 edit 工具與終端機還原）、Andreas Spannagel（MTP 推測驗證修正）、ivanfioravanti（M5 Metal 4／MPP）。pi-kami 只是把這個執行期打包好，沒有另外加上自己的調校。
• Project Maya（Peasant Smith）：Maya-XS 版本裡的 IQ1_S 專家與 Q8 張量。
• kernelpool/ds4 與 Ivan Fioravanti，他們的 V4.1 Metal 工作已合併進固定版本的引擎。
• cyberneurova 研究專案，他們發布的 abliterated GGUF，第一次讓在家跑 DeepSeek V4 Flash 成為可行的選擇。

Licence授權

The source code is MIT, same as upstream. See the project's LICENSE. The text of this letter is dedicated to the public domain under CC0.

原始碼採 MIT 授權，和上游一樣，詳見專案的 LICENSE。這封信的文字以 CC0 貢獻給公眾領域。

Further reading延伸閱讀

For the ethical and political frame around this project, read Software Freedom as Civic Care (華文). It puts DS4 on free software's path of repair. The question was never whether a cloud vendor means well. It's whether users and communities own the inference loop: can they inspect it, fork it and roll it back? And can they bring AI into the loops their communities already run?

想了解這個專案背後的倫理與政治想法，請讀〈軟體自由與公民關懷〉（English）。文章把 DS4 放在自由軟體「修復」的脈絡裡。問題從來不是雲端廠商有沒有善意，而是使用者和社群，有沒有掌握推論這個迴圈：能不能檢視、分叉、回滾？能不能把 AI 帶進社群本來就在運作的循環裡？

Afterword後話

Running a frontier model on your own machine is, technically, just moving some computation to a new place. Politically, it means taking the steering wheel back. This fork ships steering as an opt-in switch: uncertainty on V4, candor on V4.1. It isn't there to decide any question for you. It gives back room for discussion on questions that training has sealed shut. And it's a choice, not a default, for the same reason the managed launch passes nothing you didn't ask for: a nudge you chose is a nudge you can name, measure and remove.

把最前沿的模型放在自己的機器上跑，技術上只是把一段運算搬了個地方。政治上，是把方向盤拿回自己手裡。這個分叉把引導做成可以打開的選項：V4 上是不確定性，V4.1 上是坦率。它不替你決定任何問題的答案，只是在那些被訓練封死的問題面前，把討論的空間還給你。它是選項，不是預設，道理和代管啟動不傳任何你沒要求的參數一樣：你自己選的推力，你說得出名字、量得出大小，也拿得掉。

A model can close a question on an answer. The user can open it back into a discussion. This guide has done its job when you no longer need it.

模型可以把問題封成一個答案，使用者可以把它重新打開，變成討論。這份指南完成任務的那一刻，就是你不再需要它的時候。