statch用本地 AI 越久，我越觉得这不是一个“装个模型就完事”的事。你真正需要的是一套能跑、能管、能守住的完整方案。从模型下载、推理加速，到 API 封装、权限控制，再到数据备份和异常排查，哪一环掉了链子，整个“堡垒”都会跟着塌。我这套名为 IronClaw 的本地部署方案，就是把这些问题一次性梳理清楚，让你在自己的设备上搭建一个完全可控、断网也能用、数据不出内网的 AI 服务。
这篇指南不是泛泛地讲概念，而是我这两年反复折腾本地 AI 部署的完整记录。里面包含了硬件怎么评估、量化模型怎么选、推理参数怎么调、服务怎么加固，还有一堆踩坑笔记。不管你是刚接触本地 AI，还是已经能跑通基础模型但想进一步做专业部署，这份内容都能直接抄作业。
1. 为什么是本地 AI：IronClaw 解决的核心问题
先聊点实在的。很多人一开始接触 AI 都是从网页版聊天或云 API 开始的，但用着用着就会发现几个绕不开的问题：数据全部经过第三方服务器，敏感信息根本不敢往上放；每次都要联网，网络一波动整个工作流就断了；按 token 计费，跑一批实验数据月底账单让人肉疼；更麻烦的是，你很难自定义底层模型结构，想要接入自己的知识库、开发自己的 Agent，处处受制于人。
本地 AI 想解决的核心就一条：把“租别人的模型”变成“用自己的模型”。你的聊天记录、文档、知识库全部留在自己的磁盘上，没有数据外传，断网也能照常使用，模型行为完全可以自己调。IronClaw 正是在这个背景下被设计出来的，它不是一个单独的模型文件，也不是一个孤立的启动脚本，而是一整套围绕本地推理构建的服务栈：模型运行时、Web 交互界面、API 网关、日志监控、备份恢复，全都串在一起。
我把这套东西称为“堡垒”，因为本地 AI 真正难的不是跑起来，而是跑得稳、跑得安全。默认配置下模型服务只会监听本地回环地址，外部设备根本访问不到；一旦你想让同一台机器上的其他应用调用，或者让局域网内其他设备访问，暴露面就会变大，这时候必须有一套完整的认证和访问控制策略。IronClaw 的设计哲学就是：默认安全，最小依赖，所有组件都可以随时重建。每个模块都尽量独立，日志、模型、配置、数据全部分离，这样就算某个组件挂了，也不会拖垮整个服务。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与硬件评估
动手之前，你必须先搞清楚自己的硬件到底能撑起多大的模型。很多新手一上来就下载 70B 的大模型，结果发现显存完全不够，CPU 推理慢到没法用，最后只能删掉重来。这一步花 20 分钟做评估，后面能省下一天的时间。
2.1 硬件底线与显存计算
大语言模型运行时最核心的资源是显存。模型权重的内存占用有一个很好用的估算公式：权重显存大约等于参数量乘量化位数再除 8。以 7B 模型为例，如果使用 4bit 量化，权重部分大约是 7GB 乘 0.5，也就是 3.5GB 左右，加上一些额外开销，大概 4GB 出头。而如果是 8bit 量化，同样的模型就大约需要 7GB 权重，再加上推理期间产生的 KV 缓存和激活值，实际占用会更高。
我给你的建议是：先看显卡显存，再定模型规模。4GB 显存或者 6GB 显存，适合跑 1.5B 到 3B 的小模型；8GB 到 12GB 显存，可以跑 7B 到 8B 的模型，这是目前性价比最高的甜点区间；16GB 到 24GB 显存，可以尝试 13B/14B 甚至 32B 的量化版本。如果只有内存没有独立显卡，也不是完全不能跑，用 CPU 加内存的方式跑 7B 以下的小模型还是可行的，但速度会比较感人，每秒几个 token 是常态。
具体到设备，NVIDIA 显卡是兼容性最好的选择，CUDA 生态里几乎所有推理引擎都能直接调用。Apple Silicon 芯片的 Mac 则因为统一内存架构，可以跑更大的模型，但需要注意选择支持 Metal 的推理后端。AMD 显卡现在也能通过 ROCm 跑通大部分流程，但配置复杂度会高一些，不建议新手一上来就选这条路线。
2.2 软件依赖与驱动
硬件看完了，再看系统软件。我的建议是优先使用 Linux 系统，Ubuntu 22.04 或 24.04 都可以，如果你对 Linux 不熟悉，用 Docker Desktop 加 WSL2 在 Windows 上也是可行的替代方案。这里顺便提一句，无论用哪种方式，都要先确认 GPU 驱动能被系统正常识别。
装完驱动之后先执行 nvidia-smi，如果终端能正确打印出显卡型号、驱动版本和显存信息，说明驱动没问题。然后再装 NVIDIA Container Toolkit，这一步是为了让 Docker 容器能访问 GPU。在 Ubuntu 上，安装完 toolkit 之后还要配置 runtime：sudo nvidia-ctk runtime configure --runtime=docker，最后重启 Docker 服务。验证容器是否能看到 GPU，可以跑这条命令：
bash复制docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
如果容器里能正常输出显卡信息，你的环境就完全准备好了。
3. 5 分钟跑通 IronClaw 安装
环境就绪后，就可以安装 IronClaw 了。我设计这套方案时，最重要的一个原则是“重来成本要低”。所以 IronClaw 不直接往系统里写乱七八糟的依赖，所有核心组件都跑在 Docker 容器里，宿主机只需要一个 Docker 环境和一个装模型的目录。
3.1 安装步骤与验证
先拉取项目配置目录，然后启动核心服务。如果你用的是我整理的 Docker Compose 配置，整个启动过程只需要几条命令：
bash复制git clone https://example.com/ironclaw.git
cd ironclaw
cp .env.example .env
docker compose up -d
第一次启动会自动拉取推理运行时、Web 界面和 API 网关这几个镜像。启动完成后，先检查容器状态：
bash复制docker compose ps
正常情况下，你应该能看到三个服务都在 running 状态。然后查看 Web 界面端口是否监听：默认配置下，Web 界面跑在 8080 端口，打开浏览器访问 http://127.0.0.1:8080，能看到登录页面就说明基础服务起来了。API 网关则跑在 11434 端口，用 curl 快速验证一下：
bash复制curl http://127.0.0.1:11434/v1/models
这条命令会返回一个模型列表，如果列表为空也不要慌，因为此时你还没下载任何模型。
3.2 目录结构解析
IronClaw 的目录结构设计是有讲究的，每个目录都有明确职责，这样排查问题时能快速定位：
text复制ironclaw/
├── models/ # 模型文件存放目录，可映射到独立磁盘
├── data/ # Web 界面、知识库、配置数据
├── backups/ # 定期备份输出目录
├── logs/ # 容器日志和访问日志
├── certs/ # TLS 证书目录
└── .env # 全局配置文件
我特别建议把 models 和 data 放到一块独立的大容量磁盘上，因为模型文件动辄几个 GB，而且后续还会不断扩充。backups 目录则要放到另一块物理磁盘或者网络存储上，防止源盘故障时备份一起丢失。
4. 模型选型与量化方案
服务跑通了，接下来要选模型。这是影响体验最深的一步，也是最多人在这里迷路的环节。网上可选的模型五花八门，如果只看下载量随便挑一个，大概率会用得别扭。
4.1 如何判断哪个模型适合你
我的建议是先明确自己的场景，再按场景选模型。日常对话、写文案、做翻译，选一个 7B 到 8B 的中型模型就够了，这类模型速度最快，误差也小。如果你主要拿 AI 辅助编写代码，那要选代码专项模型，而不是通用的对话模型。如果你想做知识库问答或者 RAG 应用，那么模型的基础推理能力和上下文长度就比什么都重要，这时可以考虑 13B/14B 甚至更大的模型。
拿当前几个常见的开源模型举例：Qwen2.5 7B/14B 在中文场景下表现非常均衡，既能日常对话也能处理结构化任务；Llama 3.1 8B 在英文和创意内容上素质不错；Mistral 7B 则胜在轻量和速度。不要把模型当成“越大越好”，模型越大，推理越慢，显存占用越高，如果不是刚需，7B 到 8B 反而是日常体验最流畅的区间。
4.2 量化等级的选择逻辑
大模型原始参数位宽通常是 FP16 或 BF16，直接运行需要极大的显存。量化的目的就是降低每位权重占用的位数，让模型能塞进你的显卡里。目前最主流的格式是 GGUF，它支持从 2bit 到 8bit 的多种量化等级，常见的几个档位如下：
| 量化档位 | 7B 模型近似大小 | 质量损失 | 适用场景 |
|---|---|---|---|
| Q2_K | 约 2.7GB | 明显 | 显存极小时救急 |
| Q4_K_M | 约 4.1GB | 较小 | 大多数用户的甜点档 |
| Q5_K_M | 约 4.8GB | 很小 | 显存有余量时优先 |
| Q8_0 | 约 7.0GB | 几乎无损 | 追求质量且显存充足 |
我个人几乎固定使用 Q4_K_M，因为它的体量和质量达到了一个非常平衡的点。如果显卡显存还有富余，再上 Q5_K_M，感知到的质量提升其实是有限度的；Q8 以上的提升在肉眼上反而不太明显，但体积却直线上升。选模型时先确认自己的显存预算，再用量化大小去匹配，这样模型一加载就不会出现 OOM。
5. 核心配置：打造真正可用的推理服务
很多入门教程到模型能跑通对话就停了，但真正的项目落地远不止于此。你要让模型服务能稳定对外提供 API，要控制并发，要设置权限，还要能随时看到运行状态。这一章讲的就是这些“上线级”配置。
5.1 运行时参数调优
先说上下文长度。上下文长度决定模型一次性能“记住”多少内容，单位是 token。默认情况下，很多推理引擎只给 2048 个 token 的上下文，这在实际使用中是不够的，你贴一段稍长的文档进去，系统直接截断。我在 IronClaw 里默认配置为 8192，如果你的显存足够且处理长文本场景多，可以调到 16384 甚至 32768。
但要注意，上下文长度不是白给的。KV 缓存会随着上下文长度线性增长，计算公式大致是 2 乘层数乘上下文长度乘注意力头维度乘每个缓存元素的字节数，显存不够时，把上下文调大反而会直接导致 OOM。所以我的建议是：先定上下文长度，再根据它反推 KV 缓存需要多少显存，最后用剩余显存去匹配模型权重。
温度这个参数也很关键，它控制模型输出的随机性。做创意写作可以调到 0.8 到 1.0，让输出更有发散性；做代码生成或结构化数据输出，建议调低到 0.2 以下，减少胡说八道。实际使用中，我习惯给不同场景配置不同的温度参数，这比同一个温度跑到底效果要好得多。
另外一个很容易被忽略的参数是 GPU 层数卸载。如果你的显存装不下整个模型，可以把一部分层放在 GPU，其余放在内存，这就是所谓的“部分 GPU 卸载”。这种方式能让显存不足的机器勉强跑起更大的模型，但速度会明显下降。如果你显存刚好够，一定要设置完整卸载，避免某些层跑到 CPU 上导致速度暴跌。
5.2 访问入口与 API 封装
本地 AI 跑起来之后，你肯定不想只在终端里跟它对话。IronClaw 提供两个入口：一个是开箱即用的 Web 界面，适合日常人机交互；另一个是 OpenAI 兼容的 API 网关，适合给外部应用和脚本调用。
API 网关默认兼容 OpenAI 的 /v1/chat/completions 和 /v1/embeddings 这两套接口。这意味着现有的 OpenAI SDK 只要改一下 base_url 和 API key，就能直接切换到本地模型。举个例子，Python 代码可以这样连接：
python复制from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:11434/v1",
api_key="local-key",
)
resp = client.chat.completions.create(
model="qwen2.5:7b",
messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
这里要提醒一下，不要在代码里硬编码密钥，环境变量或者配置文件里统一管理更安全。API key 和明文流量是两回事，只要你的服务需要对外提供访问，就必须考虑加密传输，否则密钥就是裸奔的。
6. 加固：构建“坚不可摧”的本地 AI 堡垒
名字叫“坚不可摧”，这块内容自然是重头戏。本地 AI 一开公网或局域网访问，马上就会面临扫描、爆破、未授权调用各种威胁。很多人的模型服务就是这么被拿去当免费算力的。这部分我不是想制造焦虑，只是告诉你，不做防护就开外网端口等于把家门钥匙放在门口脚垫下面。
6.1 网络暴露面与访问控制
IronClaw 默认就把推理引擎绑定到 127.0.0.1 上，也就是只有本机才能访问。这个默认配置非常安全，也符合最小暴露原则。当你确实需要让局域网内的其他设备访问时，再去有意识地开放端口，而不是一开始就图省事设置成 0.0.0.0。
如果一定要对外开放，我建议在推理引擎前面加一层反向代理。用 Nginx 或 Caddy 做 TLS 终止、API key 校验和速率限制。配置文件里至少要有这几项：强制 HTTPS 跳转、限制请求体大小、设置来源 IP 白名单、接口限速。比如用 Nginx 限制单 IP 每分钟最多 60 个请求，能很大程度降低被刷的风险。
同时，管理后台和 API 需要分开对待。Web 管理界面不要用默认密码，第一次登录强制改成复杂密码，有条件可以接上双因素认证。API 访问则尽量生成独立密钥，每个应用用不同的 key，一旦某个应用出问题可以单独吊销，不影响其他应用。我的经验是，任何情况下都不要把推理端口直接映射到公网，必须经过带 TLS 和认证的网关。
6.2 数据保护与备份恢复
本地 AI 真正宝贵的资产不是模型文件本身，而是你积累的对话记录、知识库数据和微调数据。模型文件可以从网上下载回来，但你在 Web 界面上整理的资料一旦丢了，就是永久损失。所以备份策略必须做起来。
IronClaw 的备份方案分成两级。第一级是定期把 data 目录和 backups 目录打包，通过 crontab 定时任务执行；第二级是在关键操作前手动执行一次快照，比如导入新知识库或调整模型配置之前。备份脚本很简单，核心就是压缩加复制：
bash复制tar -czf backups/ironclaw-$(date +%F).tar.gz data/ models/ 2>/dev/null
我把这一行写在计划任务里，每周日凌晨执行一次，并保留最近 30 天的备份文件。磁盘层面的加密也不能忽略，Linux 下可以用 LUKS 对数据盘做整盘加密，Windows 下用 BitLocker，这样即使硬盘被偷走了，里面的数据也很难被读取。
最后再强调一条运维铁律：容器内尽量不使用 root 用户。IronClaw 的容器默认以普通用户运行，宿主机上也不要随便给整个目录开 777 权限。用最小权限原则跑服务，即使某个组件被攻破，攻击者拿到的也是受限环境，影响范围会小很多。
7. 常见问题与排查技巧实录
再稳的堡垒也会遇到攻击和故障。这里我把这一年多实际踩过的坑和排查方法整理成一份速查记录，遇到问题时可以直接对照。
7.1 显存不足与 OOM
如果你启动模型后服务直接崩溃，或者生成到一半突然报错，很可能是显存不够。先执行 nvidia-smi 查看当前显存占用，如果已经基本打满，说明模型加上下文超出了硬件承载能力。解决方案有三条，按优先级排列：降低上下文长度、换用更低档位的量化模型、关闭并行加载其他模型。
OOM 还有一个隐蔽的问题：同时加载多个模型。IronClaw 默认会保留已加载的模型一段时间，如果你连续加载了多个不同模型，显存可能被全部占满。遇到这种情况，可以手动清理已加载模型，让当前模型独占显存。
7.2 推理速度异常慢
速度慢首先要分清楚是哪个环节慢。输入一句话要等几秒才开始输出，这往往发生在模型加载阶段，也就是从磁盘读出权重到显存的过程，这跟磁盘读写速度和模型大小有关。已经出字但速度很卡，这就是推理本身的吞吐问题。
用 docker compose logs 查看推理引擎日志，重点观察是否出现了类似“offloaded X layers to CPU”的字眼。如果是因为显存不足，部分层被卸载到了 CPU，速度会断崖式下降。另一种常见情况是 GPU 没有真正被使用，比如在容器里忘了加 --gpus all，或者驱动配置不对，推理全程走 CPU。这时可以用 nvidia-smi 看运行时的 GPU 利用率，如果 GPU 利用率长期为 0%，肯定有问题。
7.3 访问不通与启动失败
服务启动失败最常出现在端口被占用。IronClaw 默认使用 8080 和 11434 端口，如果你本机已经有应用占用了这两个端口，容器启动就会失败。排查命令很简单：
bash复制ss -tlnp | grep -E '8080|11434'
看到有进程监听的话，要么停掉那个进程，要么在 .env 文件里改端口映射。还有一个容易忽略的点是防火墙。很多 Linux 发行版默认开启 UFW 防火墙，即使容器已经把端口映射出来了，防火墙没放行，外部依然无法访问。这里要确认：仅本机访问就保持防火墙默认拒绝；设局域网访问才放行对应端口；公网访问则必须交给有认证的网关。
日志是最好的老师。几乎任何异常，都可以从 docker compose logs 里找到端倪。我建议在排查时先看日志，再改配置，不要盲目重启服务。反复重启只会让问题更难定位。
8. 收尾：使用 IronClaw 的几点真实体会
把整套东西跑起来之后，你会发现自己对 AI 的理解会发生一个微妙的变化：以前是“我有一个接口能调”，现在是“我有一个模型体系可以控制”。这种掌控感在排查问题、调整参数、引入新模型时特别明显。我的经验是，本地 AI 部署最大的门槛其实不是技术，而是心态。不要一上来就追求最大最强的模型，先把手头硬件的上限摸清楚，从 Q4_K_M 的中型模型开始，跑通一整套服务，再逐步扩展。
还有一个小技巧想分享给大家：每次调整配置前，先记下当前的系统状态和用的模型版本，而不是“感觉有问题了才开始找原因”。我用 IronClaw 这一年多，光是这种随手记录的习惯，就帮我省下了无数排查时间。好的部署方案从来不是一次性搭好的，而是在一次次维护和调整中变得越来越顺手。