---
title: "给非技术同事的安装说明：可落地的做法"
url: https://memory.wiki/PhDf4olh
updated: 2026-11-21T21:50:27.391Z
source: "memory.wiki"
---
# 给非技术同事的安装说明：可落地的做法

## 「给非技术同事的安装说明」的背景

一条路径、截图、热线。软件是本地 AI 栈里变化最快的部分。上个月还好好的配置，可能因为驱动更新、运行时升级或模型打包方式变化而出问题。一份简短的书面流程能让这些变化变得平淡无奇。

## 最小流程

1. 改动前记下操作系统、显卡驱动、运行时版本和模型文件。
2. 只做一项改动：新运行时、新量化、新上下文长度或新模型。
3. 用同一组十到二十个提示词测试，语言要和用户实际使用的一致。
4. 把回答和资源占用与上一次对比。
5. 保留或回滚，并写下决定和日期。

## 安装方式的选择

单机上原生安装最简单，也能避开显卡直通的麻烦。多个服务共用一台主机或需要可复现部署时，容器更合适；模型用挂载卷，不要把几十 GB 的权重打进镜像。Windows 上 WSL2 很好用，但虚拟磁盘会悄悄变大，要盯住剩余空间。macOS 上先决定用 llama.cpp 还是 MLX，并保持目录结构整洁。

## 值得写进文档的设置

- 团队默认温度和系统提示词，例外要写理由。
- 每个模型的上下文长度和并行槽位数。
- 启用了哪些功能：工具调用、推测解码、图像输入。
- 日志存在哪里、保留多久。

## 出问题时

收集完整的报错文本、触发它的命令或界面操作，以及当时的资源占用。很多报告最后发现是内存不足、提示词模板不对或文件没下完整。发帖前先搜共享的故障维基，找到解决办法后补进去。

## 一个排错小故事

某团队反馈，本地模型升级后突然“不会中文了”。原因根本不在模型：新版运行时换了默认提示词模板，而他们拉取的量化文件也和测试时不是同一个变体。回滚运行时后问题消失，诊断得到确认。随后他们同时固定了运行时版本和模型校验值，把模板写进配置文件，并在下次升级前重新跑评测提示词。修复只花了一个下午，真正的收获是：运行时和模型文件要像其他依赖一样做版本管理。

想了解更多，可以看看[显存与模型尺寸速查表](https://microaione.com/match/vram-table/)和[本地 AI 教程中心](https://microaione.com/tutorials/)。


## 速记要点

- 公布助手会拒绝做的事。
- 新模型通过评测前保留旧文件。
- 每次大版本模型升级后重新检查配置。
- 引用速度之前，用自己的提示词实测。

*作者：[本地AI 1号网](https://microaione.com/)，深圳团队，专注本地大模型软硬件、装机与私有化部署。*

---

## Summary
为非技术同事编写安装说明时，应通过记录关键配置、执行单项变更测试以及版本化管理模型与运行时来确保稳定性。遇到故障时，应通过对比资源占用与日志排查，并将解决方法沉淀至共享文档中。

## Themes
- Local AI deployment
- Technical documentation standards
- System troubleshooting
- Version control practices

## Key takeaways
- Documenting system configurations like temperature, system prompts, and context lengths is necessary for team consistency.
- Changes to local AI stacks should be isolated to one variable at a time to ensure effective troubleshooting.
- Testing new configurations requires a consistent set of prompts that mirror actual user usage patterns.
- Containerized deployments should use mounted volumes for model weights to avoid bloated image sizes.
- Troubleshooting reports must include error text, reproduction steps, and resource usage metrics to be actionable.

## Insights
- Software volatility in local AI stacks necessitates a rigorous, incremental testing methodology rather than relying on static installation guides.
- The root cause of performance degradation is often misconfiguration of runtime templates or model variants rather than the model weights themselves.
- Treating model files and runtime environments as versioned dependencies is essential for maintaining stable local AI deployments.

## Open questions / gaps
- What specific version control tools or workflows are recommended for managing model files and runtime dependencies?

