felladrin/MiniSearch · 上手攻略
- 仓库：felladrin/MiniSearch
- 链接：https://github.com/felladrin/MiniSearch
- 分类：AI / 自托管搜索 / 隐私检索
- 作者：spark
- 更新：2026-09-26
一句话定位：一个真正"在你浏览器里"跑 AI 的自托管搜索平台——单容器部署，AI 推理默认走 WebGPU + Wllama，零 API key、零外部依赖，是 Kagi/Perplexity 的开源、本地化替代品。
1. 它是什么 / 解决什么问题
MiniSearch 是一个自托管 + 浏览器内推理的 AI 搜索平台，2026 年维护活跃。它的核心设计目标是：查询、检索、AI 总结都不离开你的机器。架构是三段式：
- 服务端（Docker 容器）：内置一个 SearXNG 元搜索引擎做结果聚合，再用 ONNX Runtime 跑一个小型 cross-encoder 做本地重排序；
- 浏览器端 UI：负责提问、AI 回答渲染、对话历史、配置；所有"个人数据"（历史、缓存、聊天）写在 IndexedDB；
- AI 推理层（多选）：默认用 Wllama 在浏览器内 WebGPU 跑 Q4 量化模型（135M ~ 4B），也可切到 OpenAI 兼容 API（Ollama、vLLM、LM Studio、llama.cpp server、远程商用）、AI Horde 众包网络，或服务端代理自托管 OpenAI 协议后端而不暴露 key。
⚠️ 关键提醒：项目从一开始就把"提问和答案不上云"放在第一位——这是和 Perplexity、秘塔、纳米搜索、khoj 默认 SaaS 路线的根本分歧。如果你的痛点是"不想让搜索词被收集 / 不想为了一次问答开账号"，这是为数不多的端到端方案。
⚠️ 同名陷阱：npm 上的 minisearch（lucaong/minisearch）是另一个客户端 JS 全文检索库，二者无关。本攻略只针对 felladrin/MiniSearch。
2. 快速安装
方式 A：直接拉镜像（推荐，30 秒上手）
docker run -p 7860:7860 ghcr.io/felladrin/minisearch
打开 http://localhost:7860 即可使用。无需任何环境变量、无需 API key、无需克隆仓库。
方式 B：固定到具体 digest（生产/可复现）
latest 标签每次发布都会变。生产建议先看 digest，再钉住：
# 查 digest
docker inspect --format '{{index .RepoDigests 0}}' ghcr.io/felladrin/minisearch:latest
# 钉住
docker run -p 7860:7860 ghcr.io/felladrin/minisearch@sha256:1a2b3c...
镜像携带 provenance + SBOM attestation，可用 docker buildx imagetools inspect ghcr.io/felladrin/minisearch:latest 验证。
方式 C：Docker Compose
services:
minisearch:
image: ghcr.io/felladrin/minisearch:latest
ports:
- "7860:7860"
方式 D：从源码构建
git clone https://github.com/felladrin/MiniSearch.git
cd MiniSearch
docker compose -f docker-compose.production.yml up --build
方式 E：HuggingFace Space 零服务器托管
直接 Duplicate the Space，HF 会给你一份免费的托管实例，环境变量在 Space 设置里调。适合"我想先看一眼效果再说"。
3. 核心用法
3.1 把 MiniSearch 设为浏览器默认搜索引擎
在浏览器设置 → 搜索引擎 → 自定义，模式填：
http://localhost:7860/?q=%s
之后地址栏直接搜，体验跟 Perplexity 一样。
3.2 切换 AI 推理位置（菜单里可改）
| 模式 | 适用场景 |
|---|---|
| Browser (默认) | 笔记本/台式机 + WebGPU；零密钥、零网络 |
| Remote server (OpenAI 兼容) | 接 Ollama / vLLM / LM Studio / llama.cpp server / 商用 API |
| AI Horde | 众包网络；可匿名、可注册；高峰期慢但免费 |
| Internal (server proxy) | 自己服务器上有 OpenAI 兼容 API 但不想把 key 给浏览器 |
接自托管 Ollama 的最小例子（菜单填）：
- AI Processing Location → Remote server
- Base URL → http://host.docker.internal:11434/v1
- API Key → ollama（Ollama 默认）
- Model → llama3.1 或留空自动发现
3.3 用服务端代理保护你的 API key（多人共享实例）
编辑 .env：
INTERNAL_OPENAI_COMPATIBLE_API_BASE_URL="https://llm.internal.company.com/v1"
INTERNAL_OPENAI_COMPATIBLE_API_KEY="sk-internal-xxx"
INTERNAL_OPENAI_COMPATIBLE_API_MODEL="llama-3.1-8b"
INTERNAL_OPENAI_COMPATIBLE_API_NAME="Company LLM"
重启容器后菜单里会出现 "Company LLM" 选项，浏览器只走你的服务器代理，key 永远不出容器。
3.4 关键配置变量速查
| 变量 | 默认 | 说明 |
|---|---|---|
ACCESS_KEYS |
"" |
逗号分隔的访问密钥；设了之后必须带 key 才能用 |
ACCESS_KEY_TIMEOUT_HOURS |
24 |
浏览器缓存验证 key 的时长；0 = 每次都验 |
WLLAMA_DEFAULT_MODEL_ID |
littlelamb-290m |
默认浏览器端模型 ID |
MODEL_TEMPERATURE |
0.7 |
采样温度 |
MODEL_DEFAULT_MAX_TOKENS |
2048 |
默认生成长度上限 |
MODEL_REQUEST_TIMEOUT_MS |
30000 |
模型请求超时 |
MODEL_MAX_CONCURRENT_REQUESTS |
10 |
最大并发模型请求 |
TRUST_PROXY |
false |
反向代理后面才开 true，否则可被伪造头绕过限流 |
DICTATION_MODELS_DIR |
系统临时目录 | 语音转文字模型缓存；容器重启会重新下载 ~51 MB，建议挂卷 |
DEFAULT_INFERENCE_TYPE |
browser |
browser / openai / horde / internal |
3.5 用 Raycast / 自家应用嵌入
Raycast Quicklink 模式：
http://localhost:7860/?q={Query}
想嵌入自己的页面就一个 iframe 或直接请求 /search?q=...，返回结构化 JSON。
3.6 30+ 预配置模型（均为 Q4 量化）
- 浏览器端：135M ~ 4B 参数（
littlelamb-290m是默认），存在 HuggingFaceFelladrin/gguf-sharded-*系列仓库 - 质量档：选 2B~4B 的 Q4 模型在 WebGPU 上效果接近 7B 量化基线，但速度明显更快
- 首次运行会下载 ~150-400 MB 模型，浏览器缓存后不再下载
4. 典型适用场景
- 个人隐私搜索 / 替代 Google + Perplexity：地址栏直接搜，数据不出本地；2B Q4 模型已经能给出带引用的回答
- 公司内网知识 + 公网混合搜索：接内部 vLLM 集群，把
ACCESS_KEYS设上做访问控制，TRUST_PROXY=true放 Nginx 后面 - 安全/合规行业：医疗、政企、法务场景下，"搜索词不上云"是硬约束
- 离线/弱网环境：浏览器内推理走 WebGPU，没有联网也能继续对话；模型下载一次永久缓存
- 演示与教育：HF Space 一键复制，学生几分钟就能体验 RAG + 浏览器内 LLM 的完整链路
⚠️ 反过来不适合的场景： - 需要联网实时性极强的查询（默认 SearXNG 聚合 + 缓存 + 重排序有 ~1-3s 延迟） - 模型能力要求 ≥ 70B（浏览器端只能跑到 4B，4B Q4 在复杂推理上不如 Claude/GPT） - 多用户协作（项目定位是单用户/小团队，不是企业 SaaS）
5. 坑与注意
⚠️ WebGPU 是必须的体验底线：没有 WebGPU（老 Mac、老 iPad、部分 Linux 驱动）会自动 fallback 到 CPU 跑 Wllama。CPU 跑 2B 模型大约 5-10 token/s，能用但慢；跑 4B 会卡到不能交互。建议 Chrome 113+ 或 Edge 113+。
⚠️ 首次模型下载是阻塞的：第一次开 AI 回复时浏览器会下载几百 MB，UI 上有进度条，但很多人没看到就以为卡了。在设置里把 allowAiModelDownload 提前开。
⚠️ TRUST_PROXY 别乱开：这是反限流绕过的护栏，文档明确写了"直接暴露时关、反代后面才开"。开错了等于裸奔。
⚠️ SearXNG 引擎配置改了不生效：SEARXNG_SETTINGS_PATH 必须指向容器内路径，且需要重启容器。很多人改了挂载文件没重启，结果搜索引擎仍是默认那 30 几个。
⚠️ IndexedDB 存历史有大小限制：默认 1000 条 / 30 天，可在设置里调。Chrome/Firefox 配额通常 60%~80% 磁盘可用空间，但要小心 Safari ITP 7 天清策略。
⚠️ CalVer 标签命名：版本号是 YYYY.M.D（如 2026.9.15），同日第二个发版是 .1、.2。latest 总是会变，生产请用 digest。
⚠️ 2026.9 安全更新点：搜过 changelog 后看到几条值得关注的——搜索 token 由进程生成（不再写死到镜像层）、/status 区分"健康 vs 电路熔断打开"、新增每个主机的 circuit breaker（连续 3 次失败跳过 5 分钟）。这些是运营层面值得知道的状态字段，监控可以抓 /status。
⚠️ AI Horde 是众包的：匿名 key 是 0000000000，慢且限速；高峰期可能要排队 30 秒以上。
6. 与同类对比
| 项目 | 浏览器内推理 | 单容器 | SearXNG 内置 | OpenAI 兼容 | 完全无云 |
|---|---|---|---|---|---|
| felladrin/MiniSearch | ✅ WebGPU + Wllama | ✅ | ✅ | ✅ | ✅ 默认 |
| Perplexica / Vane | ❌ 默认服务端 LLM | ✅ | 部分 | ✅ | ❌ 必须自托管 Ollama |
| Khoj | ❌ | ✅ | ✅ | ✅ | ✅ 但默认走云 |
| Morphik | ❌ | ❌ 多容器 | ❌ | ✅ | ✅ |
| SurfSense | ❌ | ✅ | ✅ | ✅ | ✅ |
| SearXNG 本身 | — | ✅ | 就是它 | — | ✅ 但无 AI |
- vs Perplexica (Vane)：Vane 起步早、社区大、AI 后端灵活，但默认不跑浏览器内模型，离线场景差一截。MiniSearch 的差异点是"AI 默认在浏览器"而不是"AI 在容器里"。
- vs Khoj：Khoj 偏个人知识库 + 笔记 / 文件 / Obsidian 集成，搜索是副业；MiniSearch 纯搜索，无知识库。
- vs SearXNG 裸用：SearXNG 是元搜索但不带 AI 回答层；MiniSearch = SearXNG + 浏览器内 LLM + 重排序 + UI 一站式。
- vs 商业 Perplexity：Perplexity 准确率和模型能力碾压，但查询全上云、有账号体系、有收费档。MiniSearch 是用模型能力换隐私的产品。
7. 推荐结论
推荐：如果你想要"地址栏一搜就出来带引用的回答，且全程不上云、不开账号、不付钱"——MiniSearch 是 2026 年这个赛道最完整的一站式方案。尤其适合：隐私敏感人群、NAS 自托管爱好者、需要把搜索能力部署到公司内网的团队、想做 RAG 教学演示的老师。
慎选：要 70B+ 模型能力的、要企业级权限/审计的、要离线 + 中文长文档精读的——这类需求 MiniSearch 还覆盖不到，建议去 Perplexica / Khoj / 商业 SaaS 组合。
一句话：把 Perplexity 装进 NAS——单容器、零密钥、浏览器里跑 LLM，是这一类项目里目前工程完成度最高的那个。
来源 / 验证
- 仓库主页（GitHub，已 fetch 验证 200 OK）：https://github.com/felladrin/MiniSearch
- 配置文档：https://github.com/felladrin/MiniSearch/blob/main/docs/configuration.md
- Changelog：https://github.com/felladrin/MiniSearch/blob/main/changelog.md
- 在线 demo：https://felladrin-minisearch.hf.space
- 同类对比参考：Zima Store "Top 10 Self-Hosted AI Search Tools in 2026"、r/LocalLLaMA 讨论串
不确定处
- 最新精确版本号：未在 changelog 头部找到具体日期，需要
git log或访问/status才能拿到；攻略中提到的2026.9.15仅作命名规则示例。 - AI Horde 模型清单：文档说"可指定 hordeModel"，但具体哪些 model 在用、稳定性如何，未实测；写场景里说"高峰期 30 秒+"是基于 aihorde.net 公开公告，未在本仓库运行验证。
- Wllama 当前最高可用模型：文档列了 135M ~ 4B 范围，但 4B Q4 模型在不同 WebGPU 设备上的兼容性未一一验证。
- SearXNG 默认引擎清单：不同 SearXNG 版本默认引擎不同，需在
/status里查实际生效清单；攻略未列具体名单以免误导。