内容
<p align="center">
<img src="./docs/assets/ironrag-logo.svg" alt="IronRAG logo" width="180">
</p>
<h1 align="center">IronRAG</h1>
<p align="center">Self-hosted document search and grounded answers for teams and AI agents.</p>
<p align="center">
<a href="https://github.com/mlimarenko/IronRAG/stargazers"><img src="https://img.shields.io/github/stars/mlimarenko/IronRAG?style=flat-square" alt="Stars"></a>
<a href="https://github.com/mlimarenko/IronRAG/releases"><img src="https://img.shields.io/github/v/release/mlimarenko/IronRAG?style=flat-square" alt="Release"></a>
<a href="https://hub.docker.com/r/pipingspace/ironrag-backend"><img src="https://img.shields.io/docker/pulls/pipingspace/ironrag-backend?style=flat-square" alt="Docker Pulls"></a>
<a href="./LICENSE"><img src="https://img.shields.io/github/license/mlimarenko/IronRAG?style=flat-square" alt="License"></a>
</p>
<p align="center">
<img src="./docs/assets/readme-pipeline-illustration.png" alt="IronRAG pipeline from messy data to structured knowledge" width="980">
</p>
## Quick start
```bash
curl -fsSL https://raw.githubusercontent.com/mlimarenko/IronRAG/master/install.sh | bash
```
Or from source:
```bash
git clone https://github.com/mlimarenko/IronRAG.git
cd IronRAG
# First start only: the API and workers refuse to start without a credential
# master key, and .env.example ships it empty. Add
# IRONRAG_AI_PROVIDER_API_KEYS_JSON_B64 to the same file.
if [ ! -f .env ]; then
sed "s|^IRONRAG_CREDENTIAL_MASTER_KEY=.*|IRONRAG_CREDENTIAL_MASTER_KEY=$(openssl rand -base64 32)|" \
.env.example > .env
fi
docker compose up -d
```
The `install.sh` wizard writes such a key for a fresh `.env` on its own. Never
overwrite an existing `.env`, and never regenerate its key while the deployment's
PostgreSQL volume persists: the stored credentials would stay undecryptable. To
change the port, resource profile, provider keys or bootstrap admin on an
existing install, re-run `install.sh`, which keeps the stored secrets.
Open [http://127.0.0.1:19000](http://127.0.0.1:19000), create an admin account, upload a document, and ask a question.
Wizard details, non-interactive CI installs, provider keys, and telemetry:
[docs/en/INSTALL.md](./docs/en/INSTALL.md) · [docs/ru/INSTALL.md](./docs/ru/INSTALL.md)
## Stack and capabilities
- **Self-hosted runtime** — Docker Compose (PostgreSQL + pgvector, Redis, backend, worker, frontend) or Helm on Kubernetes; data stays on your servers
- **Typed knowledge graph** — entities, typed relations, and chunk-level citations; hybrid retrieval across vector, lexical, graph, and technical-fact lanes
- **Native MCP server** — 23 tools for documents, graph, web ingest, and grounded `grounded_answer`; works with Claude Desktop / Code, Cursor, Codex, VS Code (Continue / Cline / Roo), Zed, OpenClaw, Hermes, and custom HTTP MCP clients
- **Provider-agnostic AI** — OpenAI, DeepSeek, Qwen / DashScope, GPTunnel, OpenRouter, RouterAI, MiniMax, Ollama, LiteLLM / OpenAI-compatible gateways; eight binding purposes (`extract_text`, `extract_graph`, `graph_entity_type`, `embed_chunk`, `query_compile`, `query_rerank`, `query_answer`, `agent`) with per-currency cost rollups in the UI
- **Code-aware + CPU-first ingest** — 15-language tree-sitter AST; JSON / YAML / TOML / CSV / XLSX parsers; technical facts (paths, endpoints, env vars, error codes); Docling CPU OCR for PDF / DOCX / PPTX without a GPU
- **Multi-tenant IAM** — principals, scoped tokens (system / workspace / library), permission groups, audit log
- **Durable ops** — restart-safe document jobs with page-range checkpoints; durable assistant turns that recover after stream drops; streaming `tar.zst` backup / restore
- **Pluggable connectors** — BookStack, Confluence, YouTrack, Git repos, or build your own; see [connectors/](./connectors/README.md). They live in this repository and ship on this version (poll + webhook intake)
<p align="center">
<img src="./docs/assets/readme-flow.gif" alt="IronRAG demo in light and dark themes: document upload, graph layouts, and assistant" width="1280">
</p>
## Configure AI
Put provider keys in `IRONRAG_AI_PROVIDER_API_KEYS_JSON_B64` and keep
`IRONRAG_CREDENTIAL_MASTER_KEY` set (generated by `install.sh` on fresh installs).
Then bind models under **Admin → AI → Bindings**.
- Provider catalog and binding purposes → [AI-BINDINGS.md](./docs/en/AI-BINDINGS.md)
- Credential encryption and key rotation → [CREDENTIAL-ENCRYPTION.md](./docs/en/CREDENTIAL-ENCRYPTION.md)
## Pipeline
<p align="center">
<img src="./docs/assets/readme-architecture.png" alt="IronRAG pipeline: ingest and enrich sources, persist knowledge in PostgreSQL with pgvector, and retrieve evidence for grounded answers. Source storage and Redis workers have separate roles; AI models resolve through per-purpose bindings." width="1280">
</p>
1. **Ingest** — files, web, API / MCP → recognition → structured chunks → PostgreSQL
2. **Build memory** — embeddings, technical facts, entities and typed relations
3. **Query** — hybrid retrieval (vector, lexical, graph, facts) → grounded answer with citations
4. **Route providers** — each LLM stage uses its binding; switch models without rewriting the pipeline
Deep dive: [docs/en/PIPELINE.md](./docs/en/PIPELINE.md) · [docs/en/README.md](./docs/en/README.md)
## Documentation
| Topic | English | Russian |
| --- | --- | --- |
| Install & bootstrap | [INSTALL.md](./docs/en/INSTALL.md) | [INSTALL.md](./docs/ru/INSTALL.md) |
| Architecture | [README.md](./docs/en/README.md) | [README.md](./docs/ru/README.md) |
| Pipeline | [PIPELINE.md](./docs/en/PIPELINE.md) | [PIPELINE.md](./docs/ru/PIPELINE.md) |
| MCP | [MCP.md](./docs/en/MCP.md) | [MCP.md](./docs/ru/MCP.md) |
| AI bindings | [AI-BINDINGS.md](./docs/en/AI-BINDINGS.md) | [AI-BINDINGS.md](./docs/ru/AI-BINDINGS.md) |
| Credential encryption | [CREDENTIAL-ENCRYPTION.md](./docs/en/CREDENTIAL-ENCRYPTION.md) | [CREDENTIAL-ENCRYPTION.md](./docs/ru/CREDENTIAL-ENCRYPTION.md) |
| Capacity & Compose / Helm | [CAPACITY-PLANNING.md](./docs/en/CAPACITY-PLANNING.md) | [CAPACITY-PLANNING.md](./docs/ru/CAPACITY-PLANNING.md) |
| IAM | [IAM.md](./docs/en/IAM.md) | [IAM.md](./docs/ru/IAM.md) |
| Changelog | [CHANGELOG.md](./CHANGELOG.md) | — |
More topics (CLI, frontend, webhooks, benchmarks, Ollama) live under [`docs/en/`](./docs/en/README.md) and [`docs/ru/`](./docs/ru/README.md).
## Working on IronRAG
**Vector dimension is a property of a library, not a constant of the product.**
It comes from the active `EmbedChunk`/`EmbedQuestion` binding. Do not add a
product-wide `const VECTOR_DIM`. PostgreSQL shards
(`knowledge_chunk_vector_d{dim}`, `knowledge_entity_vector_d{dim}`) are created
and configured through `infra/postgres/pg_vector_config.rs` in both the search
store and snapshot restore, including constraints on existing shards. Changing
dimension requires re-embedding into a new shard. Test vector storage with at
least two dimensions.
**No hardcoded user-facing strings in `apps/web/`.** Every visible text is
`t('namespace.key')`, with the key present in both locales
(`shared/i18n/ru.json`, `en.json`). Interpolating values is fine; the template
lives in the locale file. `make frontend-i18n-audit` (part of `frontend-check`)
walks the TypeScript AST and understands dynamic keys and plural forms.
The audit rejects `defaultValue` on static keys: translations belong in the
locale files. Dynamic keys may use an API-produced runtime token as a fallback.
**A change to the answer pipeline is verified through both channels.** The
built-in assistant is an MCP-client-shaped agent over the same tool surface an
external MCP client gets, and `grounded_answer` stays the one high-level
grounded-answer tool — the contract is `apps/api/tests/MCP_PARITY.md`. After a
change in retrieve, answer or the MCP tools, run the regression through the UI
*and* through an external MCP client. One channel healthy and the other
degraded is not a release; a tool reachable only from the UI is a defect.
### Documentation
- [`CLI`](./docs/en/CLI.md) — maintenance commands and schema rollout.
- [`INSTALL`](./docs/en/INSTALL.md), [`PIPELINE`](./docs/en/PIPELINE.md), and
[`AI-BINDINGS`](./docs/en/AI-BINDINGS.md) — setup and runtime behavior.
- [`CHANGELOG`](./CHANGELOG.md) — release changes.
### Development checks
- **Your own database on your own port.** The default in
`apps/api/src/app/config/loading.rs` is
`postgres://postgres:postgres@127.0.0.1:5432/ironrag`, and
`TempPostgresDatabase` starts with `drop database if exists`. Point
`IRONRAG_DATABASE_URL` at a PostgreSQL you own — settings are read with the
`IRONRAG_` prefix, and a bare `DATABASE_URL` is ignored.
- **Integration tests are one crate**, `apps/api/tests/it`, not a set of
binaries. The required suites are `BACKEND_INTEGRATION_SUITES` in the
`Makefile`, and a full run needs `--all-targets` — without it the binaries
under `tests/` are skipped along with their compliance gates.
- **The criterion is the `N passed` line, not the exit code.** A suite with no
matching test prints `test result: ok. 0 passed` and exits zero. Some tests
sit behind `#[cfg(feature = "test-support")]`, so a run without
`--features test-support` produces an empty green binary.
- **A wedged ingest queue looks like ordinary load.** A poisoned job (a terminal
`ops_async_operation` behind a claimable `ingest_job`) holds `leased` rows,
and those count against `ingestion_max_parallel_jobs_per_library`. The tell is
the same `job_id` in "claimed ingest job" dozens of times in a row and no
other. Check with:
```sql
select j.queue_state, o.status, count(*)
from ingest_job j
left join ops_async_operation o on o.id = j.async_operation_id
where j.queue_state in ('queued', 'leased')
group by 1, 2;
```
The poisoned ones are those whose `o.status` is terminal.
- **CI checks merge requests and protected default-branch pushes.** Migration
checks and ops self-tests run in both. Protected default pushes build backend,
frontend, Confluence, YouTrack and BookStack images; backend and BookStack
have separate image security gates. Other local checks use the Make targets.
- **Release publication is opt-in.** Set the pipeline input `release=true` and
run the manual `release` job on a protected default-branch push. It requires
the version, four deployed image producers, migration/ops checks and both image
security gates. `release-bump` selects patch (default), minor or major.
`release:promote` verifies reservation and source identity, promotes the four
deployed image digests and publishes the GitLab release; `deploy:gitops`
follows. BookStack is built separately from that four-image promotion set.
Schema-rollout fences guard release, promotion and GitOps deployment.
- **A snapshot import answers `202`.** The terminal status lives in
`GET /v1/ops/operations/{id}`; `curl --fail` is green on an operation that
failed afterwards.
## License
[MIT](./LICENSE)
连接信息
猜你喜欢
X视频文案提取
X / Twitter 视频文案提取 MCP Server — 专注解析 X 平台公开视频链接(x.com / twitter.com status...
MarkItDown MCP
MarkItDown-MCP是一个轻量级服务器,用于将URI转换为Markdown。
MarkItDown
将文件和办公文档转换为Markdown的Python工具。
worldmonitor
实时全球情报仪表盘。基于人工智能的新闻聚合、地缘政治监测和基础设施跟踪,提供统一的态势感知界面。
OmniRoute
永不停息的编码。免费 AI 网关 — 一个端点,160+ 提供商,零停机时间。智能 4 级自动降级(订阅 → API → 廉价 →...
文件系统操作
Node.js MCP服务器,用于文件系统操作,支持动态访问控制。