共计 4126 个字符，预计需要花费 11 分钟才能阅读完成。
很多极客在家里折腾 NAS，最开始都止步于影视刮削、照片同步和挂 PT。但随着本地大模型和各类 Code Agent 的火热，大家开始尝试把自家 NAS 变成“私人代码中枢”：让它既能索引平时写的所有散碎脚本、开源项目、技术笔记，又能通过局域网的 IDE 插件（如 Continue 或 Roo-Code）秒级检索代码片段。然而一旦把几万个文件扔给传统的 LangChain 玩具级方案，NAS 往往很快被巨额内存吞噬、CPU 风扇狂转，甚至由于锁盘引发容器直接 OOM 崩溃。
上个月我把工作机里累积了五年的 18 万行多语言代码库和 Obsidian 笔记全部灌入家用 NAS（i5-12400 + 32GB 双通道 + NVMe 缓存盘，跑 TrueNAS Scale / 纯 Docker 环境）。在这套系统跑顺之前，我踩了嵌入模型选型失误、分块截断破坏语义、磁盘 I/O 锁死等大坑。本文将这套轻量、抗揍且内存占用控制在 3GB 以内的架构和实测避坑经验整理出来，供大家直接抄作业。
一、架构选型：为什么弃用 Milvus 和 Chroma？
在 NAS 这种算力受限（通常只有核显或中低端独显，甚至纯 CPU）、注重资源占用的机器上，软件架构的选型决定了系统的生死：
- 向量数据库选型：Milvus 虽然适合分布式超大规模生产环境，但一堆依赖组件（etcd、MinIO、Pulsar/Kafka）把 NAS 内存直接吃空；Chroma 轻量但并发读写和元数据过滤较弱，且基于 SQLite 底层在高负载下容易锁表。最终我选用了 Qdrant（Rust 编写），内存控制极致，支持磁盘向量量化（On-disk Payload），单镜像启动，对 Docker 极其友好。
- 嵌入模型（Embedding Model）： 选用
bge-m3。它支持 8192 的超长上下文窗口，同时支持稠密向量（Dense）、稀疏向量（Sparse，类似 BM25）和多向量检索，最重要的是对中英混排、Python/Go/Shell 代码标识符非常敏感。在 CPU 推理模式下，通过 FastEmbed 引擎运行量化版本，延迟完全可以接受。
二、Docker Compose 服务编排实战
首先在 NAS 的高速存储池（建议使用 NVMe SSD 挂载，机械盘随机读写无法承受高频向量检索）建立目录结构，编写 docker-compose.yml：
version: '3.8'
services:
qdrant:
image: qdrant/qdrant:v1.9.2
container_name: local-qdrant
restart: unless-stopped
ports:
- "6333:6333"
- "6334:6334"
volumes:
- /mnt/fast-pool/appdata/qdrant/storage:/qdrant/storage
environment:
- QDRANT__SERVICE__HTTP_PORT=6333
- QDRANT__SERVICE__GRPC_PORT=6334
- QDRANT__STORAGE__PERFORMANCE__MAX_SEARCH_THREADS=4
deploy:
resources:
limits:
memory: 4G
embed-server:
image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.5
container_name: bge-embed-server
restart: unless-stopped
ports:
- "8080:80"
volumes:
- /mnt/fast-pool/appdata/huggingface:/data
command:
- "--model-id"
- "BAAI/bge-m3"
- "--max-client-batch-size"
- "32"
deploy:
resources:
limits:
memory: 3G
这里有几个关键参数需要明确：
- 限制最大搜索线程：
QDRANT__STORAGE__PERFORMANCE__MAX_SEARCH_THREADS=4避免检索瞬间把 NAS 的 CPU 核心占满，导致宿主机其他服务（如 SMB 传输或 Plex 解码）掉线。 - 分离推理引擎： 不要在写入脚本中用 PyTorch 本地硬跑模型。采用 HuggingFace 的 Text Embeddings Inference (TEI) 镜像，使用 Rust 编写的高并发推理引擎，吞吐量比 Python 的 Sentence-Transformers 高出至少 3 倍，且内存利用极低。
三、代码切割与向量入库脚本优化
很多现成知识库方案最拉胯的地方在于文档切分（Chunking）：直接按 500 字符强行截断，一个完整的 Python 类或 Go 函数被拦腰砍断，导致大模型在检索后根本看不懂上下文。我在工程实践中使用基于 AST（语法抽象树）的语法感知切割，遇到纯文档才退回重叠字符切割：
import os
from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct
import requests
QDRANT_HOST = "http://192.168.1.100:6333"
EMBED_URL = "http://192.168.1.100:8080/embed"
COLLECTION_NAME = "nas_codebase"
client = QdrantClient(url=QDRANT_HOST)
# 1. 初始化集合（1024 维为 bge-m3 稠密向量维度）if not client.collection_exists(COLLECTION_NAME):
client.create_collection(
collection_name=COLLECTION_NAME,
vectors_config=VectorParams(size=1024, distance=Distance.COSINE),
)
def get_embeddings(texts: list[str]) -> list[list[float]]:
"""批量从 NAS 的 TEI 服务获取向量"""
response = requests.post(EMBED_URL, json={"inputs": texts}, timeout=30)
response.raise_for_status()
return response.json()
def batch_upsert(points_buffer):
"""批量写入 Qdrant，降低磁盘 I/O 阻塞"""
client.upsert(
collection_name=COLLECTION_NAME,
points=points_buffer,
wait=False # 异步持久化，极大提升吞吐
)
print("向量数据库与嵌入连接就绪，可以开始灌入数据。")
实战踩坑：批量导入时的内存与锁盘危机
在最初灌入 18 万行代码时，如果每一段代码获取完向量立即执行 client.upsert，NAS 上的机械阵列会发生严重的 I/O 阻塞，同时 Qdrant 的 HNSW 索引不断触发重构，CPU 占用居高不下。 务必设置批量写入缓冲区（比如攒够 200 个分块提交一次），并且在初次全量建立索引时，关闭 wait=True 参数。 让数据先进入 Write-Ahead Logging (WAL)，待夜间闲时再去构建 HNSW 向量索引图。
四、实测检索性能对比
在 Intel i5-12400、分配了 4 核心给容器的测试环境下，针对包含 24,000 个代码块（Python、Rust、Markdown）的向量库进行真实检索测试：
| 检索方案 | P95 响应延迟 | 静态内存占用 | 长代码段命中准确率（Top-3） |
|---|---|---|---|
| Python 本地模型 + ChromaDB | 840 ms | 4.8 GB | 68.5% |
| TEI (bge-m3) + Qdrant（本文方案） | 142 ms | 1.9 GB | 91.2% |
可以看到，剥离了臃肿的 Python 运行时后，基于 Rust 构建的基础底座响应速度大幅提升，更重要的是，在并发查询下 NAS 没有发生过一次负载失控导致的死机。
五、IDE 客户端联动：接入 Continue 插件
数据入库后，在本地 VS Code 或 Cursor 中安装 Continue 插件，修改 ~/.continue/config.json，将其上下文检索提供者（Context Provider）指向我们的 NAS：
{
"models": [
{
"title": "DeepSeek-Coder-Local",
"provider": "ollama",
"model": "deepseek-coder:6.7b",
"apiBase": "http://192.168.1.100:11434"
}
],
"customCommands": [],
"contextProviders": [
{
"name": "http",
"params": {"url": "http://192.168.1.100:6333/collections/nas_codebase/points/search"}
}
]
}
现在，当你在 IDE 中输入 @codebase 我的数据清洗管道是怎么写的？ 时，编辑器会自动通过局域网高带宽发起向量匹配，毫秒级拉出 NAS 里记录的最佳实战片段并塞入上下文窗口，既保护了私有核心代码不泄露给云端 SaaS，又完全不用消耗主力工作机的算力。
总结与避坑心得
在低功耗 NAS 上折腾 AI 工具链，务必牢记以下三条硬原则：
- 数据路径必须落到 SSD 存储池： 任何向量数据库在更新索向量索引时的高并发随机寻道，都能把普通机械硬盘折磨得生不如死。
- 尽量远离纯 Python 后端服务： 在部署 Embeddings 和 Vector DB 这类基础设施时，优先选择 Go 或 Rust 编写的高效单体容器。
- 严控模型上下文： 不需要无脑追求大体量模型，
bge-m3搭配优秀的分块清洗逻辑，在个人知识库和代码检索场景下，体验远胜于给 NAS 强行挂载臃肿的几十亿参数巨无霸。
通过这套极客方案，沉睡在 NAS 里的硬盘文件终于不再只是冰冷的归档数据，而是随时能被本地 IDE 调用的第二大脑。
===END===
