免费且私有:用本地模型驱动readmex,实现100%私密的AI文档生成
免费且私有:用本地模型驱动readmex,实现100%私密的AI文档生成
readmex 是一款免费的开源 AI 文档生成工具,可为任意项目自动生成结构完整的 README 和交互式 Wiki。它最大的亮点是完全支持本地模型——只要你把语言模型、文生图模型指向本机部署的服务,代码就不会离开你的电脑,实现 100% 私密、零 API 花费的 AI 文档生成。这篇文章带你从零完成本地模型配置,全程只需几分钟。
为什么需要本地模型:代码隐私的 3 个痛点
如果你用过云端 AI 写文档,多半会纠结这三件事:
- 🔒 代码安全:把源码片段发给云端 API,等于把代码"晒"给了第三方。私有项目、内部系统尤其敏感
- 💰 API 费用:大项目动辄几十个文件,按 token 计费的费用很快就不低
- 📡 网络依赖:内网环境、无外网服务器根本用不了云端服务
而 readmex 的架构天然为本地化而设计:它对任意"OpenAI 兼容接口"都透明支持,意味着你本地用 Ollama、vLLM、LM Studio 跑起来的模型,都可以直接接上。
上图是 readmex 的完整工作流:项目文件经过过滤后,本地分析出技术栈与文件结构,再交给大模型填充到模板 src/readmex/templates/BLANK_README.md 中生成最终文档。
readmex 的 3 个本地模型组成
readmex 的 AI 能力由三类模型承担,每一类都可以独立切换为本地服务:
| 组件 | 作用 | 配置项 | 本地替代方案 |
|---|---|---|---|
| LLM(语言模型) | 生成项目描述、脚本说明、README 正文 | LLM_BASE_URL / LLM_MODEL_NAME |
Ollama、vLLM 等本地推理服务 |
| T2I(文生图) | 为项目生成 Logo | T2I_BASE_URL / T2I_MODEL_NAME |
本地 Stable Diffusion / ComfyUI |
| Embedding(嵌入) | 为代码建立 RAG 语义索引 | LOCAL_EMBEDDING |
默认就是本地模型,无需配置 |
特别值得强调的是第三点:readmex 的代码 RAG 检索系统(核心实现在 src/readmex/code_rag.py)默认 LOCAL_EMBEDDING=true,会使用本地嵌入模型在机器内完成全部向量化与检索,代码向量一步都不会外传。这是"100% 私密"的关键一环。
模型请求的发送逻辑集中在 src/readmex/utils/model_client.py,它只关心 base_url 指向哪里——云端还是本地,对它而言没有区别。
一键安装:readmex 快速安装步骤
前置要求仅 Python 3.7+。
方式一:pip 直接安装(推荐)
pip install readmex
方式二:从源码运行
git clone https://gitcode.com/gh_mirrors/rea/readmeX
pip install -r requirements.txt
最快配置方法:本地模型接入指南
readmex 支持两种配置方式(实现见 src/readmex/config.py),环境变量优先级更高:
方式一:环境变量(适合 CI/CD 或临时使用)
export LLM_API_KEY="local" # 本地服务通常填占位值即可
export LLM_BASE_URL="http://localhost:11434/v1" # 指向你的本地 LLM 服务
export LLM_MODEL_NAME="qwen2.5" # 你本地加载的模型名
export T2I_BASE_URL="http://localhost:7860/v1" # 指向你的本地文生图服务
export T2I_MODEL_NAME="sd1.5"
export LOCAL_EMBEDDING="true" # 使用本地嵌入模型
方式二:全局配置文件(适合日常本地使用)
创建 ~/.readmex/config.json,工具会自动读取。仓库中提供了完整模板 config_template.json,把默认指向云端的 base_url 改成你本地服务的地址即可:
{
"LLM_API_KEY": "local",
"LLM_BASE_URL": "http://localhost:11434/v1",
"LLM_MODEL_NAME": "qwen2.5",
"T2I_API_KEY": "local",
"T2I_BASE_URL": "http://localhost:7860/v1",
"T2I_MODEL_NAME": "sd1.5",
"LOCAL_EMBEDDING": "true"
}
💡 小提示:本地 LLM 服务一般要求 OpenAI 兼容接口。Ollama 自带 http://localhost:11434/v1 端点,开箱即用;首次运行时若发现缺少密钥,readmex 也会交互式提示你填写并自动保存到全局配置。
本地文生图:自己生成项目 Logo
Logo 生成是 readmex 的招牌功能之一——它会根据项目上下文构造提示词,再调用 T2I 模型画图(逻辑见 src/readmex/utils/logo_generator.py)。
只要你的本地绘图服务暴露了 OpenAI 兼容的 /images/generate 接口(Stable Diffusion WebUI、ComfyUI 等均有相应插件或兼容模式),把 T2I_BASE_URL 和 T2I_MODEL_NAME 填上即可。readmex 会智能区分服务商,对非 OpenAI 接口自动采用兼容参数,避免报错。
一键生成:README 与交互式 Wiki
配置完成后,在项目根目录执行:
# 生成本地 README(交互式模式)
readmex
# 指定项目路径与输出目录
readmex --project-path /path/to/your/project --output-dir /path/to/output
# 免交互批量生成
readmex --silent
# 生成交互式 Wiki 网站并本地预览
readmex --website --serve
运行结束后你会得到 5 样成果:项目结构文件 project_structure.txt、脚本描述 script_description.json、依赖清单 requirements.txt、项目 Logo logo.png,以及最终的 README.md。--website 模式还能把文档升级为可搜索的 MkDocs 交互式站点,本地服务预览后一键部署。
隐私保障:readmex 如何做到代码不出本地
把整条数据流串起来看,readmex 的隐私边界非常清晰:
- Embedding 阶段:默认使用本地嵌入模型,代码切块、向量化、语义检索全部在本机完成
- LLM 阶段:请求只发往你指定的
LLM_BASE_URL——配置为localhost时,流量仅在本机回环网络中流动 - T2I 阶段:Logo 提示词同样指向本地服务
只要三个 BASE_URL 都指向本地,整个生成过程的每一字节数据都停留在你的机器里。相比需要把仓库推送到云端的在线文档服务,这就是本地化部署的核心价值:免费(软件本身 MIT 许可)+ 私有(数据闭环)+ 可控(模型可换)。
常见问题速查
- 本地模型支持哪些? 任何提供 OpenAI 兼容 API 的推理框架都可以,模型名称通过
LLM_MODEL_NAME指定即可 - 配置没生效? 环境变量会覆盖配置文件,运行报错时 readmex 会打印当前生效的配置来源,方便排查
- 想要更快的生成? 调整
MAX_WORKERS控制并发线程数(默认 10),并发越高越快 - 调试不想烧 token? 使用
readmex --debug可跳过 LLM 调用快速验证流程
写在最后
readmex 证明了 AI 文档生成不必以牺牲隐私为代价:一套 OpenAI 兼容的配置体系,就能让语言模型、文生图、代码检索三块能力整体"落地"到本地。对于有代码保密要求、成本敏感或内网环境的团队来说,用本地模型驱动 readmex 或许是当下最省心的 100% 私密文档方案。装上它,几分钟内就能让 AI 在局域网内为你的项目写出漂亮的 README 与交互式 Wiki。


