carrel README

项目的 README,来自 github.com/FengZhenfei/carrel。合并为一个 markdown 文件:README.md。

Carrel

English | 中文

tests License: MIT

Ontology-Augmented Generation for AI agents.

Carrel is a self-hosted knowledge base for AI agents. It automates document parsing, indexing, and retrieval, with optional knowledge graphs. Agents use its API to retrieve source passages, images, and related facts, then generate their own answers.

Use it to give an agent access to a collection of product documents, research, contracts, meeting notes, or other files that change over time. A web console manages knowledge bases, models, and processing tasks. A bundled search skill connects agents such as Claude Code and Codex to the retrieval service.

0.4.1 general retrieval benchmarks and codebase capabilities · Full 0.4.0 capability evaluation

Features · Evaluation · Design · Quick start · Agent integration · Documentation

Features

0.4.3 changes and upgrade steps — Consistent document publication, version-bound evidence, table parsing repairs, and bundled code grammars.

Capability evaluation

Across 275 text queries, 0.4.1 reached 93.45% evidence Hit@5 and 0.8141 MRR@10. In a separate study of 24 code questions, Haiku answered 13 completely from the first response and 23 with Skill follow-up. 0.4.1 evaluation

The full 0.4.0 evaluation also covers graph rebuild stability, time-scoped evidence, conflicts and ontology governance. Full 0.4.0 technical report

How it works

flowchart LR
    D[Document folders] --> P[Parse and chunk]
    P --> I[Vector and keyword indexes]
    P --> G[Optional knowledge graphs]
    I --> R[Retrieval API]
    G --> R
    R --> A[AI agent]
    A -->|Follow-up queries| R

Carrel uses MinerU and native parsers for ingestion. Standard uses Qdrant, OpenSearch and Neo4j; Light uses embedded LanceDB and DuckDB. SQLite tracks files and tasks in both editions. Model services run independently, locally or through compatible hosted endpoints. See Architecture for the pipeline and retrieval design.

Design

Carrel provides general knowledge storage, retrieval, and evidence interfaces. Entities, relationships, and facts retain sources, time information, and conflicts so agents can check and use them alongside the original documents. Default retrieval retains historical and future source claims. An explicit time query selects the relevant evidence; reviewed corrections record which sources and identities the decision applies to. The Agent Loop plugin is in development and not yet implemented. It is intended to use these interfaces to continuously learn an enterprise ontology, seek clarification from relevant people, and maintain correction rules.

Routine graph updates merge new and changed content incrementally. Configured time or change thresholds trigger full rebuilds, balancing update cost with overall consistency. Parsing, indexing, and graph construction are maintained separately: rebuilding a graph can reuse parsed content and chunks while preserving RAG indexes.

Requirements

Platform Deployment
Linux with NVIDIA GPU GPU parsing with NVIDIA Container Toolkit; container scheduling
Linux without GPU CPU parsing; connect to model services on another host or a provider
macOS with Docker Desktop CPU parsing and application containers, including scheduling
Windows Use WSL2; native Windows deployment is not supported

Example setup describes the author's installation on an NVIDIA DGX Spark and some lighter alternatives.

Quick start

1. Deploy the services

git clone https://github.com/FengZhenfei/carrel.git
cd carrel
./deploy.sh --standard --build
# Or use embedded storage:
# ./deploy.sh --light --build

The optional script prepares Compose configuration and starts the application, background scheduler and selected dependencies. You can also use Compose directly. First startup downloads MinerU parser assets. See Container deployment.

2. Configure model endpoints

Choose Standard for Qdrant, OpenSearch and Neo4j, or Light for embedded LanceDB and DuckDB. The edition is fixed for that deployment directory. Both include MinerU; Light has no database containers. See Storage editions.

In System settings, configure LLM, Embedding and Reranker endpoints, model IDs and API keys. Register a vision-capable LLM and select it as the Multimodal model for each knowledge base. Images, charts and table review share that selection. Models can run on your own machines or hosted platforms. Carrel does not start these model services or download their weights. See Model configuration.

3. Add documents

Open the console at http://127.0.0.1:9800. Put documents in data/runtime/mirror/<folder>/, then enable that folder in the console. Each enabled folder becomes a knowledge base; scheduled tasks process its files.

For a knowledge graph, register a chat model with its Max Input in the console, select it in the knowledge-base settings, and enable graph building. Check service health and task progress in the console before making your first query.

Agent integration

Install the bundled carrel-search skill in your agent, or call the API directly:

The first container start creates KB_SEARCH_TOKEN in data/config/knowledge-base.env. Set CARREL_SEARCH_TOKEN to that value:

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

For a remote agent, configure CARREL_SEARCH_BASE_URL and CARREL_SEARCH_TOKEN in its environment.

Responses include source passages and, when available, graph evidence and image information. Agents can request more context, inspect images, and follow relationships before answering. See Retrieval and API for authentication, response status, and citations.

Documentation

Guide Contents
Configuration Model endpoints, folders, per-base settings, and access control
Architecture Parsing, graph construction, retrieval, and code layout
Retrieval and API Agent setup, endpoints, evidence status, and evaluation
Retrieval and codebase evaluation (0.4.1) Document retrieval, page-image location, Skill follow-up and cross-file code analysis
Capability evaluation (0.4.0) Full technical report: retrieval, answers, temporal evidence, conflicts, ontology, rebuild stability, latency, and token usage
Operations and development Console, CLI, scheduling, troubleshooting, and tests
Test scope Shared regression contracts, deployment-specific checks, and live evaluations
Example setup The author's installation on a DGX Spark, a Mac that syncs the documents, and lighter alternatives
Docker Compose Infrastructure, model weights, and container settings
Container deployment Images, scheduling, persistent data and updates
systemd Native/source installation

Data and access

The console binds to localhost by default. For LAN access, set both KB_WEB_HOST and KB_WEB_TOKEN. Configure KB_SEARCH_TOKEN before using protected search endpoints remotely. The stores and model servers listen on loopback only, which keeps other machines out but not web pages opened in a browser on the same host, so avoid browsing the web there.

Documents and images are sent to the model endpoints you configure. Local endpoints keep model processing within your own infrastructure. See Access and data handling.

License

Carrel is licensed under MIT. Dependencies and model weights have their own licenses; see Third-party notices. Original-resolution PDF image retrieval uses an optional dependency installed with ./deploy.sh --with-pdf-images; without it, retrieval uses cached images.

carrel (FengZhenfei/carrel)

正在搜索数据库…

808 ·GitHub
这是什么?Carrel 是一个面向 AI 智能体的自托管知识库。它会自动完成文档解析、索引和检索,还可选配知识图谱,让智能体能从你的文档中提取原文段落、图片和事实,并基于这些内容作答。
这是我要导入的 Python 库,还是我要自己运行的自托管服务?它是一个自托管服务:你需要用 Docker 部署基础设施(Qdrant、OpenSearch、Neo4j)并运行 Python 应用,然后通过网页控制台和 API 进行管理,而不是把它当作库来导入。
我该怎么部署,并让文档被索引?运行部署脚本,它会检测主机、启动基础设施、安装 Python 应用并创建配置文件;然后编辑 config/knowledge-base.env 以设置模型接口,再把文件放入 runtime/mirror/,即可将其纳入知识库。
部署前需要先装什么?Python 3.12+ 和带 Compose v2 的 Docker 25+,外加一个文本嵌入(embedding)接口、一个用于图片描述的视觉语言模型接口;如果想启用知识图谱构建,还需要一个对话模型。
我能在 Windows 上原生运行吗?不能,不支持原生 Windows 部署,需要改用 WSL2。
我的文档和数据最终会发到哪里?文档和图片会发送到你配置的模型接口;如果改用本地模型接口,这些处理就会留在你自己的基础设施内,而不会交给第三方。
运行它一定需要 NVIDIA GPU 吗?只有当你想用 GPU 加速运行可选的本地模型栈时才需要;基于 CPU 的解析同样支持。
内置的 carrel-search 技能是做什么用的?它是一个现成的技能,可让 Claude Code、Codex 等编程智能体直接调用 Carrel 的检索 API,你无需自己开发集成。
检索流程底层用了哪些组件?文档摄取由 MinerU 和原生解析器完成,Qdrant 存储向量,OpenSearch 负责关键词搜索,Neo4j 处理图查询,SQLite 则记录文件和任务。
知识图谱究竟记录什么?它会从文档中提取实体类型、关系和事实,同时记录来源、时间信息,以及事实之间的冲突标记。
它能解析哪些文件类型?PDF、Word、PowerPoint、电子表格、图片、HTML、Markdown 和源代码,每种格式都有与之匹配的处理方式。
有哪些类似的项目?m_flow, semantica, LightRAG, zilan, utopia, serviette, memvid, ragflow
大小
6.6 MB
星标
808
时长
1个月
提交 · 90 天