Carrel – 面向 AI 代理的本体增强知识库

它是什么

• 一个自托管服务，让 AI 代理能够从文档集合（PDF、Word、代码、图像等）中检索最新信息。
• 它解析文件、创建向量和关键词索引、可选地构建知识图谱，并公开一个 REST API，代理可以查询该 API 获取段落、图像和图谱证据。

主要能力

功能	说明
文档解析	支持 PDF、Word、PowerPoint、电子表格、HTML、Markdown、源代码和图像。使用 MinerU 和原生解析器将文件分割为适合检索的块。
自动更新	监视指定的文件夹，重新解析更改的文件，按计划更新索引和图谱。
混合检索	结合密集向量搜索、关键词搜索、图谱遍历和视觉搜索；可以对结果进行重新排序。
知识图谱	通过聊天模型从文本中提取实体、关系、时间戳和冲突标志；将其存储在 Neo4j 中。
代理友好 API	返回源段落、原始图像和关联的图谱事实；支持分页、引文元数据和可选的认证。
Web 控制台	用于管理知识库、模型端点、计划任务和服务健康的 UI（英语/中文）。
模型集成	可与您公开的任何嵌入、视觉语言和聊天模型配合使用（本地 Docker 容器或远程端点）。

工作原理

1. 摄取 – 放置在 runtime/mirror/<folder>/ 下的文件会被解析并分块。
2. 索引 – 块被发送到 Qdrant（向量）和 OpenSearch（关键词）存储。
3. 图谱构建 – 如果启用，聊天模型会提取实体/关系并将其存储在 Neo4j 中。
4. 检索 API – 代理调用 POST /search 并附上问题；服务合并来自向量、关键词和图谱存储的结果，并返回包含文本片段、图像 URL 和图谱证据的 JSON 有效负载。
5. 反馈循环 – 代理在生成最终答案之前可以请求更多上下文或沿图谱边继续探索。

典型用例

• 让编码助手（例如 Claude、Codex）访问内部产品手册、合同或会议记录。
• 为研究论文构建可搜索的 RAG 系统，其中引文和实体关系很重要。
• 在文本检索之外，对扫描的 PDF 或设计图进行视觉搜索。

快速开始

# 1. 克隆并部署堆栈（如果可用，Docker + systemd）
git clone https://github.com/FengZhenfei/carrel.git && cd carrel
./deploy.sh                     # 检测操作系统，启动 Qdrant、OpenSearch、Neo4j 等。

# 2. 在 config/knowledge-base.env 中配置模型端点（嵌入、视觉、聊天）
#    – 可选：./deploy.sh --with-local-models 在本地运行捆绑的模型

# 3. 添加文档
#    将文件放在 runtime/mirror/<my_kb>/ 下，并在 Web UI (http://127.0.0.1:9800) 中启用该文件夹

# 4. 通过捆绑的技能或 curl 查询
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}'

响应包括匹配的段落，以及可用时的图谱节点或图像引用。

安装要求

• Python 3.12+ 和 Docker 25+（Compose v2）。
• 可选的本地模型服务需要 GPU（NVIDIA）+ 容器工具包；如果指向远程模型 API，则仅 CPU 即可运行。
• 外部服务：Qdrant（向量）、OpenSearch（关键词）、Neo4j（图谱）、SQLite（元数据）。
• 模型端点：文本嵌入、视觉语言（用于图像字幕）和聊天模型（用于图谱提取）。

文档与扩展性

• 配置 – 模型 URL、文件夹设置、访问控制的详细指南。
• 架构 – 解释解析流水线、存储选择和检索流程。
• 检索与 API – 请求格式、认证、响应模式、引文处理。
• 操作 – 控制台用法、CLI、systemd 定时器、Docker Compose 配置文件、测试。
• 技能 – 为遵循相同 API 的代理准备的即用型 carrel-search 技能。

许可证

• 代码使用 MIT 许可证；第三方依赖和模型权重具有各自的许可证（参见 NOTICE.md）。

---

Carrel 是一个全栈、本地部署的知识库平台，通过本体级别的证据增强检索，适合任何需要可靠、最新源材料的 AI 代理。