如果只看llm_wiki这个名字你可能会觉得它是个模型排行榜或者一个论文收藏夹。实际上我把它做成了一套持续更新的私有知识库用 Wiki 的形式承载大模型从原理、部署到应用的全过程。这个大模型知识库解决的不只是“笔记往哪里放”的问题更关键的是解决了“知识怎么组织、怎么检索、怎么复用”的问题。大模型领域信息更新太快今天收藏的量化教程下周可能就被新方案替代今天踩过的部署坑不记录下来过一个月再踩一次也是常有的事。llm_wiki就是为此而生的它适合一个人长期维护也适合小团队做技术沉淀。无论你是刚开始接触大模型还是已经能跑通 RAG、微调流程这套思路都能让你的知识资产真正积累下来。1. 项目动因为什么我会花力气维护一个 LLM 知识库1.1 大模型学习的最大难点不是找不到而是组织不起来很多人的资料管理方式都是同一个套路看到一篇讲 RAG 的文章先收藏遇到一个讲量化的视频先放进播放列表再加几个看起来很有用的公众号。结果等到真做项目的时候想找“7B 模型到底需要多少显存”这个最基础的数据仍然要翻半小时浏览器记录。我做过几次项目之后发现零散资料最大的问题不是“找不到”而是“没有上下文”。你找到了一篇讲 AWQ 量化的文章但里面提到的基础概念你可能早就忘了你找到了一个 vLLM 部署脚本但不知道它适配的模型版本是哪一代。这些知识之间是有依赖关系的收藏夹恰恰把这种依赖关系全部抹平了。所以llm_wiki的底层设计原则只有一条任何概念都必须有明确归属任何知识点都能在三跳以内找到它相邻的内容。比如“量化”这个词它属于“推理优化”板块同时关联“显存估算”和“部署引擎”。这样组织下来新手可以从基础概念一路索引到实操命令老手也能快速定位到某个具体参数的讨论。1.2 内容架构设计先画知识地图再填内容项目刚开始我没急着写词条而是先花了一个晚上设计目录结构。知识库最忌讳的就是“上来就写”写到哪算哪最后变成了另一个收藏夹。我最后定下来的结构是这样llm_wiki/ ├── docs/ │ ├── index.md │ ├── basics/ # Token、上下文窗口、注意力机制 │ ├── models/ # 开源模型、闭源 API、选型对比 │ ├── training/ # 预训练、微调、偏好对齐 │ ├── inference/ # 量化、推理引擎、显存优化 │ ├── applications/ # RAG、Agent、Function Call │ ├── eval/ # 评测基准、效果评估、安全测试 │ └── ops/ # 服务部署、监控、成本管理这里我需要解释一个取舍为什么没有把“提示工程Prompt Engineering”单独拆成一级目录按大多数人的习惯提示工程是接触大模型的第一站信息量也很大。但我的判断是提示工程的方法论本身是跨领域的RAG 要用提示词Agent 要用提示词普通问答也要用提示词。单独建一个目录很容易和别的板块重复最后不知道某条经验到底该放哪里。所以我把它拆进了applications下并且在basics里保留一份“提示词基础语法”的词条作为入口。目录不是越多越好而是越不重叠越好。1.3 这套结构对个人和团队的双重价值对我个人来说llm_wiki是我做项目时的“外置大脑”。每当我需要重新评估一个模型能不能上线我只要翻一遍models下的选型记录再对照inference里的显存估算表半小时内就能形成一个大致判断不必再从零开始调研。对小团队来说这东西的价值更大。团队里人人都在说 RAG、微调、量化但每个人对同一个词的理解经常不一样。有人在说“向量数据库”时指的是 Milvus有人在说“向量数据库”时只是想用 Python 的np.dot算一下相似度。如果没有一个统一术语的 wiki沟通成本会高得吓人。我在项目里还专门留了一个glossary.md用来放所有“容易被误解的术语”每次开会发现大家对不上就顺手把定义更新进去。半年下来这个词条成了团队引用率最高的文档。2. 技术选型搭建 llm_wiki 的完整方案2.1 为什么底座选 Markdown Git而不是在线文档很多人搭建知识库的第一反应是用在线文档因为方便复制粘贴多人协作也简单。但实际用下来在线文档有几个非常难受的地方第一内容多了之后搜索很弱经常搜不到准确的标题第二不可版本化改错了想回退很麻烦第三平台绑得太死想迁移数据还得依赖导出工具。所以我从一开始就决定用 Markdown Git 作为底座。Markdown 是纯文本永远不用担心格式过时Git 天然支持版本管理、分支合并和变更追溯。虽然是“土办法”但它是目前数据主权最高的方案。你换任何一台电脑git clone下来就能继续写你换任何一个文档站生成器Markdown 内容也能原封不动搬走。知识库最重要的资产是内容本身而不是承载内容的工具。这里给非技术背景的协作者说一下不会 Git 也不用怕最基础的操作只有 add、commit、push 三个命令就算完全没用过命令行照着教程敲十分钟也能跑通。如果嫌命令麻烦也可以用 VS Code 或 Obsidian 这类带图形界面的工具来提交体验和在线文档编辑器差不了太多。2.2 静态站点生成器对比MkDocs Material、VitePress、DocusaurusMarkdown 写好了总要有一个优雅的阅读入口。这里我认真对比过三个工具工具核心优势适合场景技术栈MkDocs Material文档体验好、插件丰富、配置简单纯文档型知识库、团队 WikiPythonVitePress速度快、和 Vue 生态结合好开发者文档、带交互组件Node.jsDocusaurus功能全面、能写 React 组件大型开源项目官网Node.js我最后选了 MkDocs Material。原因很简单llm_wiki的内容以文字、表格、代码片段为主不需要复杂交互组件MkDocs Material 的默认主题就自带搜索、目录、明暗切换、标签系统这些功能对知识库来说都是刚需。Python 这一个依赖项也比从头折腾 Node 项目要轻得多。2.3 我最终用的配置组合分享一份我实际在用的mkdocs.yml可以直接抄作业site_name: llm_wiki site_description: 大模型知识库从原理到部署再到应用 theme: name: material language: zh features: - navigation.instant - navigation.tracking - toc.integrate - search.suggest - search.highlight palette: - scheme: default primary: indigo toggle: icon: material/brightness-7 name: 切换夜间模式 - scheme: slate primary: indigo toggle: icon: material/brightness-4 name: 切换白天模式 plugins: - search - tags: tags_file: tags.md markdown_extensions: - admonition - pymdownx.superfences - pymdownx.tabbed - attr_list几个关键配置的使用心得navigation.instant开启后站内页面跳转不用刷新体感会流畅很多tags插件是我最依赖的一个功能它允许你在任意词条的元信息里打标签然后聚合到tags.md页面等于给“知识地图”加了第二套索引系统。admonition扩展非常实用可以写“注意”“提示”“危险”这类高亮块比普通引用更能抓住读者注意力。3. 核心知识板块内容怎么规划才不写成词典3.1 基础概念词条先定义再类比最后给例子很多人做知识库会把基础概念写成“百度百科体”一段抽象定义加上一堆难以理解的术语。这种内容写了一百条回过头来自己都不愿意看。我在basics板块总结出了一套词条模板每个概念都按这个结构写## 是什么 用一句话说清楚尽量不嵌套新术语。 ## 核心要点 - 3 到 5 个关键信息 ## 常见误区 - 至少写 2 个容易被误解的地方 ## 实操入口 - 关联的命令、配置、代码示例 ## 我的使用记录 - 在实际项目中是怎么用到的以“Token”这个词条为例。我在“是什么”部分只写了一句话“Token 是模型处理文本的基本单位可以简单理解为把句子切分后得到的小片段。”然后在“常见误区”里写Token 不等于字也不等于词中文里 1 个汉字一般是 1 到 2 个 Token英文里 1 个常见单词通常是 1 个 Token但长单词会被切成多个。最后附上了一段 Python 代码用transformers的AutoTokenizer实际算一遍“这段话到底占多少个 Token”。这种写法的价值在于它把“可被检索的定义”和“可被复用的实操”绑定在一起。别人看的时候能少走弯路你自己回看的时候也能快速找回当时的判断依据。3.2 模型部署与推理参数用可复现的记录替代“感觉”模型部署板块是整个知识库里最容易产生“干货”的地方也是最容易写成“经验玄学”的地方。比如一群人讨论“7B 模型到底需要多大显存”有人说 16G 够有人说 24G 也紧张。其实这类问题完全可以靠计算得到一个相对准确的区间。我把常用的显存估算公式整理进了inference/显存估算.md模型权重显存 ≈ 参数量 × 每个参数占用的字节数FP16 精度下10 亿参数约占用 2GB7B 模型全精度 FP16 约 14GB4bit 量化后10 亿参数约占用 0.5GB 到 0.6GB7B 模型约 4GB 到 4.5GB推理时的 KV Cache 显存 批次大小 × 序列长度 × 层数 × 隐藏层大小 × 2键和值各一份× 每个元素字节数公式不用背把它记在 wiki 里再配一两个算好的例子就够了。比如“Qwen2.5-7B-Instruct vLLM AWQ 4bit 量化最大序列长度 8192”实测时峰值显存大概是多少我在词条里写清楚了当时的卡型、驱动版本、并发数。这样过半年回来还能对比新版本推理框架的显存优化效果。这类词条的真正价值不是给你一个标准答案而是让所有经验都变成“可复现的记录”。只要参数、环境、版本列清楚了任何结论都可以被验证踩过坑的人也能一眼看出差异在哪儿。3.3 应用层RAG 和 Agent 的内容必须结合案例应用层是llm_wiki里最容易写飘的部分。如果不加约束你很容易把外网的一堆流程截图、论文摘要、概念名词搬进来最后变成一本“大模型名词大全”。我的做法是每个应用类词条必须附带一个最小可运行案例。拿 RAG 来说我在applications/rag/快速开始.md里写了 50 行以内的核心链路代码from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter loader PyPDFLoader(docs/产品手册.pdf) documents loader.load() splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap80, ) docs splitter.split_documents(documents)然后继续写 Embedding 模型的接入、向量库的存储、检索时的相似度阈值以及怎么把检索结果拼进提示词。我在词条末尾专门放了一个“真实项目记录”的章节记录了一次检索失败的原因当时 chunk 切得太碎导致每个片段的语义都不完整召回结果非常差。后来把chunk_size调到 800并保证每个 chunk 至少包含一个小节问题才解决。这种“概念 代码 失败记录”的结构才是应用层知识库该有的样子。读者能看到实际链路还能看到坑在哪里比单纯抄一份官方文档有用得多。3.4 评测与安全最容易忽略也最该沉淀很多人做知识库会忽略评测和安全相关的内容因为平时用模型只是调个 API觉得“效果听天由命”。但只要你做过几次模型选型就会发现没有统一的评测记录你根本无法回答“换这个模型到底进步了没有”这个问题。我在eval板块下维护了一套简单但可复用的评测表格评测维度常用方法备注通用能力MMLU、C-Eval、GSM8K适合横向对比模型基础能力代码能力HumanEval、MBPP适合评估代码生成场景指令遵循IFEval、AlpacaEval判断是否按用户指令执行安全与拒答红队测试、对抗样本测模型不听话时怎么办业务效果真实业务数据集最值得长期投入的部分安全测试不要等到上线前才做应该从第一天起就收集案例。哪个模型在什么提示词下说出了不当内容、哪个模型在敏感场景下拒绝得太僵硬这些记录比任何红队报告都更贴近你的真实业务。评测和安全这些内容一旦写进 wiki就要保持更新过时的结论比没有结论更容易误导人。4. 实操部署从零到上线一份 llm_wiki4.1 本地环境准备与项目初始化搭建llm_wiki只需要一台普通电脑不需要 GPU也不需要高性能服务器。我的最低配置建议是 4GB 内存、任何能跑 Python 3.10 的系统剩余磁盘 1GB 左右用于存放 Markdown 文件和依赖包。按下面的命令一次性初始化整个项目mkdir llm_wiki cd llm_wiki git init python -m venv .venv source .venv/bin/activate pip install mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs new .这里解释一下mkdocs new .做了什么它会在当前目录下生成一个docs/index.md和mkdocs.yml配置文件的骨架。之后所有文档都放到docs目录里配置文件则负责控制站点标题、主题、导航、插件等选项。4.2 打造易于维护的文档目录初始化之后我建议立刻把目录结构调整成前面设计好的样子cd docs mkdir basics models training inference applications eval ops然后修改mkdocs.yml给nav配置里加上一级目录。导航配置看起来是这样nav: - 首页: index.md - 基础概念: basics/ - 模型选型: models/ - 训练与微调: training/ - 推理与性能: inference/ - 应用开发: applications/ - 评测与安全: eval/ - 工程运维: ops/注意如果某个目录还没有index.mdMkDocs 构建时会提示导航里出现了不存在的文件。一个通用的办法是每个目录下都放一个index.md哪怕内容只有目录说明也能保证站点结构完整。4.3 本地预览用写代码的节奏写知识库内容写好后在项目根目录运行mkdocs serve然后打开http://127.0.0.1:8000就能在本地看到一个实时渲染的站点。mkdocs serve支持热更新你改完 Markdown 文件浏览器会自动刷新非常适合一边写一边看效果。我把本地预览当成日常编辑的主战场。因为它不用推送到远程也就没有心理负担格式突然乱了、链接写错了随时改。等一批内容确认没问题的再一起提交和推送。4.4 推送到 GitHub Pages半自动发布如果你想公开发布或者方便多设备访问我推荐用 GitHub Pages 托管。在仓库的 GitHub 页面里创建一个 Actions 工作流文件.github/workflows/publish.ymlname: publish on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - run: pip install mkdocs-material - run: mkdocs build --site-dir site - uses: actions/upload-pages-artifactv3 with: path: site deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - uses: actions/deploy-pagesv4这个工作流会在每次main分支收到推送时自动构建站点然后部署到 Pages。推代码时只需要git add . git commit -m update git push剩下全部交给 CI。小提示如果第一次部署后看到空白页多半是仓库的 Pages 设置里没把“Source”选成“GitHub Actions”改一下即可。5. 内容维护如何让 llm_wiki 一直活下去5.1 别憋大招用“最小更新”保持节奏知识库最容易死在“等写好一点再更新”这个念头里。一篇文章想写万全结果拖了一个月还是草稿。我的做法是采用“最小更新”策略每天只要求自己更新一个小点可以是 200 字的词条补充也可以是一条失败记录的修正甚至只是一个新链接的收录。别小看这种碎片式更新。它带来的收益是连续的你每次打开仓库都会重新看一遍旧内容相当于做了一次复习git 提交历史里也会留下一条“知识演进线”——哪天突然发现某个词条已经被修改了十几次这个知识倒逼你持续跟进最新进展。5.2 用模板和元信息管理词条质量为了让词条质量不塌方我给每个词条加了统一的元信息头。MkDocs Material 默认会读取 Markdown 开头的 YAML front matter--- title: 显存估算指南 date: 2025-06-01 tags: [inference, 显存, 部署] status: done ---status这个字段是我自己维护的draft表示草稿done表示已验证outdated表示待更新。每次打开一个词条我只要瞄一眼状态就知道它值不值得信任。这也是知识库和普通博客的最大区别普通博客写完了就不管了知识库必须给每条内容标注“有效期”。5.3 用自动化检查对抗“过期内容”内容多了之后手工检查不现实。我写了两个简单脚本塞进 CI 流程里一个检查 Markdown 文件里的坏链接包括站内链接和外部链接另一个扫描标题是否重复、是否有文件超过三个月没更新。坏链接脚本的核心思路非常朴素——用正则表达式把 Markdown 里的[text](url)全部提取出来然后逐条发起 HEAD 请求。响应码大于等于 400 的就视为失效链接。跑上这个脚本之后至少避免了“收藏夹里全是 404”的尴尬。6. 常见问题与排查实录6.1 构建、部署、维护问题速查表用 Markdown 表格列出最常见的问题现象原因处理方法构建报Config value nav: ...不存在nav里指向的文件路径写错了对照目录检查路径不要写文件名后缀之外的路径搜索不到刚写好的内容没开启搜索插件在plugins里加search并重新构建本地预览正常Pages 显示空白Pages 源设置不对在仓库设置里把 Source 改成 GitHub Actions图片显示不出来图片路径用的是本地绝对路径改为相对路径并确认图片已加入 git报告“文件编码错误”Markdown 文件编码不是 UTF-8用编辑器统一转成 UTF-8同一内容出现在多个目录没有先思考归属回到目录结构确定唯一入口用链接交叉引用这张表是我在维护过程中遇到最多的问题列表基本覆盖了大部分入门阶段的状况。6.2 几个我踩过的坑提前替你避开第一个坑是附件管理不当。刚开始我把图片统统丢在一个assets/images目录结果文件多了根本不知道哪张图对应哪篇文档构建出来的站点体积也疯涨。后来改成“每个一级目录一个assets子目录”比如docs/basics/assets/这样图片跟着内容走迁移维护都方便。第二个坑是链接全部写绝对路径。当时用 MkDocs 自带的路由工具把链接生成了/basics/token/看起来很规整但换到本地预览时路径又不一致。后来统一改成了相对链接在docs/basics/token.md里写[量化](../inference/quantization.md)而不是写[量化](/inference/quantization.md)。这样无论内容怎么搬链接都不会断。第三个坑是“抄官方文档抄得太开心”。有一段时间我把大量官方文档原封不动复制了进来结果连格式都是大段的英文句子真正要用时反而找不到想找的那一段。后来我立下一个规矩每条词条必须有自己的“实操记录”或“本地示例”没有这段内容的词条宁可先标成draft也不允许直接搬运。6.3 知识库“长不大”怎么破很多人的知识库用了一个月就荒废了原因往往是“追求完美”。我认识一个朋友花了一整个周末搭建博客框架、选主题、调字体结果两周后连一篇内容都没写。llm_wiki初期也一样我花了很长时间调主题但真正让站点变有价值的是一条条真实的部署记录和踩坑日志。如果发现自己的知识库开始吃灰我建议做一次“代码重构式”的简化把目录层级减少到两层以内删掉那些从来没有被检索过的长文把首页改成一张表直接列出“你现在最需要解决什么问题点这里能找到答案”。知识库的本质是降低获取信息的成本而不是制造另一个信息孤岛。只要你从这个角度出发持续反问自己内容就不会跑偏。7. 给后来者的真实建议如果你也想建一个类似的大模型知识库我最想说的不是“今天就用 MkDocs 搭一个出来”而是“先给自己定一个具体问题”。你是因为部署模型老算不清显存还是因为 RAG 效果总调不好围绕真实问题去写词条内容才会有生命力。我在实际维护中发现状态永远标draft的草稿比那些“看起来完美”的定稿更有价值因为它们记录了探索过程而过程里才是干货。不要怕内容粗糙不要怕框架还有瑕疵先让知识流动起来工具和结构自然会在迭代中变得越来越顺手。llm_wiki对我而言不是一个“做完就封存”的项目它更像一个会持续生长的花园——今天种一棵 RAG 的小树苗明天修一段量化的小篱笆半年后再看它已经是你离不开的依靠了。