Indexa 如何在 macOS 上通过 Ollama 构建私有 AI 知识库？

作者：袖梨 2026-09-12

Indexa 是面向 macOS 的本地优先知识库应用，依赖 Ollama 在本机生成向量和回答。安装应用并预先下载嵌入模型与聊天模型后，可以导入文档或网页，在本地完成解析、BM25 关键词检索、向量相似度检索和答案生成。它还提供来源引用、MCP 服务、OpenAI 兼容 API 与加密知识库导出。

开始前确认平台和模型条件

当前官方页面标注 Indexa v1.2，支持 Apple Silicon 和 Intel Mac，不要求注册账户。它不是自带完整模型的单体应用，需要先安装 Ollama，并通过 Ollama 下载嵌入模型和聊天模型。

默认嵌入模型为 nomic-embed-text。先在终端确认 Ollama 可用并拉取模型：

ollama --version
ollama pull nomic-embed-text
ollama list

还需下载一个适合本机内存的聊天模型。模型越大通常资源消耗越高，不应只按参数规模选择。完成一次模型下载后，若继续使用本地 Ollama 且资料已经导入，Indexa 可以在断网环境工作。

第一步：安装并验证 Ollama 连接

启动 Ollama，再打开 Indexa。官方说明中，应用会自动连接本机 Ollama，无需额外配置。首次使用不要立即导入整个资料库，先创建小型测试集合，加入一份短文档，确认嵌入和聊天模型都能响应。

若导入成功但提问失败，应分别检查：

Ollama 服务是否正在运行。
嵌入模型和聊天模型是否已经下载。
模型名称是否与 Ollama 列表一致。
本机内存是否足以加载所选模型。

第二步：按任务建立 Collection

Indexa 使用 Collection 组织知识库。每个 Collection 可以拥有自己的系统提示词、刷新周期和查询上下文，并支持跨 Collection 搜索。建议按资料用途和权限划分，例如研究论文、法律文件、客户报告和个人笔记分别建库。

一个库不应同时承载权限差异明显的资料。跨库查询虽然方便，但会扩大召回范围；使用前应确认每个参与集合都可以向当前调用者暴露。

第三步：导入文件和网页

当前支持 PDF、DOCX、TXT、Markdown、RTF、HTML、XLSX、PPTX、JSON、XML、YAML、CSV、日志、源代码，以及网页 URL。可以拖放文件，也可以粘贴单页地址或按可配置深度抓取网站。

导入前应清理重复文件、标记版本并确认文本可提取。扫描 PDF、复杂幻灯片、图表和嵌套表格可能无法仅靠文字解析保留全部含义，必须抽查。

网页来源可按小时、每天或每周自动刷新。系统使用 SHA-256 内容哈希检测变化，只有内容改变才重新导入。对于经常更新的站点，应同时记录抓取范围和页面上限，避免把无关导航或历史版本带入索引。

第四步：理解混合搜索

Indexa 同时运行 BM25 关键词检索与语义向量检索，再通过 Reciprocal Rank Fusion 合并两个排名。BM25 擅长编号、名称、函数和原句；向量检索擅长同义表达与概念相关性。

问题类型	主要检索优势	示例
精确事实	BM25	错误码 E104 的处理步骤
语义改写	向量搜索	如何撤销离职员工权限
多条件问题	混合搜索与重排	比较两版正策的例外条款

复杂问题还可以启用查询分解和 LLM 重排，但它们会增加推理时间。先用一组固定问题比较启用前后的召回结果，再决定是否长期打开。

第五步：询问并检查来源分数

聊天支持多轮上下文，回答附来源引用和相关度分数。问题应明确对象、版本和输出形式，例如：“比较 2024 与 2025 研究报告中的推理延迟结论，分别列出测量条件和来源”。

相关度分数表示检索匹配程度，不代表来源一定正确，也不代表模型总结无误。点击来源后检查：

段落是否直接支持结论。
是否遗漏否定词、例外或上下文。
数字、单位和版本是否一致。
多个来源是否真实相互印证。

第六步：验证真正离线

官方默认路径是 Ollama 本地处理，且宣称无账户、无遥测。验证时应先完成应用和模型下载，再断开网络，重新启动 Ollama 与 Indexa，测试文档搜索和聊天，并观察是否出现远端连接错误。

Indexa 也支持任意 OpenAI 兼容服务器，并可为聊天和嵌入分别配置提供方。一旦把其中一个端点改为云服务，对应的查询或文档片段就可能离开设备。因此“数据不离机”只对全部提供方保持本地时成立。

通过 MCP 连接其他 AI 工具

Indexa 内置 MCP 服务，提供 query、search 和 list_collections 三个工具，支持 SSE 与 HTTP 传输。Claude Desktop、Cursor 等客户端可以通过本机端点连接：

{
  "mcpServers": {
    "indexa": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "LOCAL_INDEXA_MCP_ENDPOINT"
      ]
    }
  }
}

占位符应替换为本机 11435 端口下的 MCP 路径。连接外部客户端前，应检查它使用的模型是否在本地。MCP 工具运行在本机，并不自动保证调用工具的聊天客户端也完全离线。

通过 OpenAI 兼容 API 查询

本地 HTTP 服务 11435 端口，提供健康检查、Collection 列表、原生查询、模型列表和聊天补全接口。Collection 会作为模型出现在兼容客户端中。

from openai import OpenAI

client = OpenAI(
    base_url="LOCAL_INDEXA_API_BASE",
    api_key="your-local-api-key",
)

response = [email protected](
    model="Research Notes",
    messages=[{"role": "user", "content": "概括主要结论并列出来源"}],
)
print(response.choices[0].message.content)

API 基础地址占位符应指向本机 11435 端口下的 v1 路径。服务包含 API 密钥认证，CORS 限制为 localhost，并对密码尝试进行速率限制。即使只在本机使用，也不应把 API 密钥写入仓库或日志。

加密导出与来源隐藏

Collection 可以导出为 `.indexa` 包，使用 AES-256-GCM 加密和 PBKDF2 密钥派生。保护模式包括“隐藏来源”和“只读”：前者允许接收者获得回答但不查看引用来源，后者允许查看和查询但不能修改。

加密包仍需通过安全渠道发送，密码应使用另一个渠道传递。隐藏来源适合分发整理后的知识，但会降低答案可审计性；高风险场景不能在无法查看证据时把回答当作最终依据。

不要把规划中的企业能力当作现成功能

当前个人功能免费且包含 MCP、API 和加密导出。服务器验证访问、集中用户管理、审计日志和企业自托管访问控制在官方页面中明确属于规划方向。团队若需要即时撤权或合规审计，应等待功能落地并完成验证，或使用已有成熟控制方案。

上线前建立回归测试

检查项	通过标准
格式解析	PDF、DOCX、PPTX 和表格抽样内容完整
精确检索	编号与专有名词稳定命中
语义检索	同义改写返回同一核心证据
无答案问题	明确承认证据不足
离线运行	断网重启后搜索和回答均可用
接口保护	无密钥无法访问，来源隐藏规则生效
加密恢复	测试包能用正确密码导入