carrel - 面向 AI 智能体的自托管知识库与检索服务

carrel 是一个面向 AI 智能体的自托管知识库项目。按项目自述，它把文档解析、索引与检索自动化，并可选地构建知识图谱；智能体通过 API 取回原文片段、图片与相关事实，再自行组织答案。它适合需要让智能体持续访问一批会变化的资料的场景，例如产品文档、研究材料、合同、会议记录等文件集合。项目同时提供一个 Web 控制台，用于管理知识库、模型与处理任务，并附带一个搜索技能，把 Claude Code、Codex 这类智能体接到检索服务上。

维护者与状态

仓库由 FengZhenfei 维护，采用 MIT 许可证。仓库创建于 2026-09-28，最后提交时间为 2026-10-15。最新正式版本为 v0.2.0，发布于 2026-10-04。截至 2026-10-18，仓库星标数为 311。

从时间线看，这是一个相当年轻的项目：创建到最新提交不足三周，版本号仍处于 0.x 阶段。项目自述中提供了较完整的文档目录，涵盖配置、架构、检索与 API、运维与开发、Docker Compose 以及 systemd 等主题，说明维护者在部署与运维层面投入了较多说明性工作。不过版本号与提交节奏也提示，接口与配置方式在后续版本中仍可能调整，接入前宜以仓库当前文档为准。

主要能力

以下能力均据项目 README 自述整理，未经独立验证：

• 多格式文档解析：支持 PDF、Word、PowerPoint、电子表格、图片、HTML、Markdown 与源代码，并针对不同格式采用相应的处理方式。
• 自动更新：通过定时任务扫描文件变化、更新索引，并维护已启用的知识图谱，使知识库跟随文件集合的变化而更新。
• 混合检索：组合向量检索、关键词检索、图谱检索与视觉检索，支持自动选择知识库，并可选用重排序。
• 知识图谱：从文档中抽取实体类型、关系与事实，并保留来源、时间信息与冲突标记。
• 智能体访问：通过 API 检索，取回上下文文本或原始图片，并在需要更多证据时沿图谱关系继续追踪。
• Web 控制台：用于配置处理流程、查看分块与图谱、跟踪任务进度、管理服务，界面提供英文与中文。

在技术组成上，项目自述使用 MinerU 与原生解析器完成入库处理，Qdrant 存储向量，OpenSearch 提供关键词检索，Neo4j 承担图谱查询，SQLite 记录文件与任务状态。模型服务可以本地运行，也可以接入兼容的托管端点。

使用入口

项目仓库地址为 FengZhenfei/carrel，部署脚本、配置说明与文档均从该仓库获取。

据项目说明，快速开始的第一步是克隆仓库并运行部署脚本：

git clone https://github.com/FengZhenfei/carrel.git
cd carrel
./deploy.sh

脚本会识别主机环境、启动基础设施、安装 Python 应用并生成配置文件；在具备用户级 systemd 的 Linux 主机上，还会启用服务与定时任务，其他主机则给出手动启动命令。首次启动会下载解析器模型。随后需要编辑 config/knowledge-base.env，设置嵌入模型与视觉模型的地址、模型名与 API 密钥；若要使用随附的本地模型，需准备权重并以 ./deploy.sh --with-local-models 部署。修改环境设置后需重启应用服务。

文档放入 runtime/mirror/ 下的目录，并在控制台（默认 http://127.0.0.1:9800）中启用该目录，每个启用的目录即成为一个知识库。若需知识图谱，还需在控制台注册对话模型并在知识库设置中启用图谱构建。

智能体侧可以安装随附的 carrel-search 技能，或直接调用检索 API：

curl -sS http://127.0.0.1:9810/search \
  -H 'Content-Type: application/json' \
  -d '{"question": "What are the delivery and acceptance requirements?", "top_k": 8}'

若设置了 KB_SEARCH_TOKEN，请求需附带 Bearer 令牌；远程智能体则通过 CARREL_SEARCH_BASE_URL 与 CARREL_SEARCH_TOKEN 环境变量配置。

许可与限制

项目采用 MIT 许可证。项目自述同时提醒，依赖项与模型权重各自遵循其自身许可证，需参阅第三方声明。

运行环境方面，项目要求 Python 3.12 及以上、Docker 25 及以上并配备 Compose v2；需要文本嵌入端点，若启用图片描述还需视觉语言端点，启用知识图谱则需要对话模型。可选的本地模型栈需要 NVIDIA GPU 与 NVIDIA Container Toolkit，同时也支持纯 CPU 解析，资源需求取决于所选模型与集合规模。平台支持上，Linux 配 NVIDIA GPU 可做 GPU 解析与本地模型服务，无 GPU 的 Linux 可做 CPU 解析并连接其他主机或服务商的模型服务，macOS 通过 Docker Desktop 运行 CPU 容器与原生 Python 服务，Windows 需使用 WSL2，不支持原生 Windows 部署。

数据与访问方面，控制台默认仅绑定本机；如需局域网访问，要同时设置 KB_WEB_HOST 与 KB_WEB_TOKEN，远程使用受保护的检索端点前应配置 KB_SEARCH_TOKEN。存储与模型服务仅监听回环地址，但这并不能阻止同一主机上浏览器打开的网页访问，项目建议避免在该主机上浏览网页。文档与图片会发送到所配置的模型端点，使用本地端点可将模型处理留在自有基础设施内。此外，PDF 原分辨率图片检索依赖一个可选组件，需以 ./deploy.sh --with-pdf-images 安装，未安装时检索使用缓存图片。