Yuxi: a self-hosted multi-tenant knowledge agent platform built from Milvus, Neo4j and LangGraph

The problem Yuxi targets: knowledge, tools and permissions in one workspace

Most RAG projects stop at a retriever and a prompt. Yuxi's README frames the target differently: it is for teams that need to control their own data, models and permissions, and it puts knowledge base retrieval, knowledge graph, LangGraph multi-agent orchestration, MCP/Skills, sandbox tools and permission management into a single workspace. That combination is the point. A team that wants document Q&A plus entity extraction plus an agent that can write files and ask a human before touching anything sensitive would otherwise assemble four or five separate services and write the glue itself. Yuxi ships the glue. The multi-tenant framing matters too: the README lists management of knowledge bases, agents, Skills and models by user, department and sharing scope, which is a governance concern that single-user RAG demos never address. If your deployment is one person and one folder of PDFs, this is more machinery than the problem needs.

How the pieces fit: FastAPI, ARQ workers, Milvus and Neo4j

The stack table in the README is explicit. The frontend is Vue 3 with Vite, Ant Design and G6 for graph rendering. The backend is FastAPI with LangGraph and an ARQ worker, which tells you that long tasks are queued rather than executed inside the request cycle. Storage is split across PostgreSQL, Redis, MinIO, Milvus and Neo4j. Document processing uses MinerU, PaddleX and RapidOCR. Deployment is Docker Compose. The data flow implied by the capability description runs roughly like this: a file is uploaded, parsed by one of the document engines into text, images and tables, chunked, embedded and indexed into Milvus; separately, entity and relationship extraction runs over those chunks and writes into Neo4j, which the README describes as building a knowledge graph index in Milvus and Neo4j. At query time the agent retrieves chunks, and the graph participates in retrieval as well. The ARQ worker is what makes the long-task UI possible: the README describes the interface showing the agent's reasoning chain, step plan, subtask status and tool-call logs while a task runs in the background. That separation between request handling and task execution is the architectural decision that everything else depends on.

Getting it running: init script, Compose, and the readiness endpoint

The README's quick start assumes Docker Engine and Docker Compose plus a working large-model API, and notes that the repository default configuration corresponds to v0.7.3. The commands are:

git clone --branch v0.7.3 --depth 1 https://github.com/xerrors/Yuxi.git cd Yuxi ./scripts/init.sh

On Windows PowerShell the equivalent is .\scripts\init.ps1. According to the README, the init script creates .env, reads a SiliconFlow API key, and generates separate security keys for JWT, API key derivation and the Sandbox provisioner. You can instead copy .env.template manually and fill in those values yourself. Then docker compose up --build -d starts the development environment. Service state is checked with docker compose ps, and readiness with curl --fail http://localhost:5050/api/system/ready, which should return a status of ready. The UI is at http://localhost:5173, where the first login initialises the super administrator, and the API docs are at http://localhost:5050/docs. Note the three distinct secrets the init script derives. Reusing one key across JWT signing, API key derivation and sandbox provisioning would collapse three trust boundaries into one, and the script exists precisely to avoid that.

Upgrades are not a pull-and-restart, and the README says so

This is the constraint that will decide whether Yuxi fits your operations. The README states plainly that upgrading from v0.7.1 or v0.7.2 to the current version cannot be done by simply running docker compose up, and directs readers to docs/advanced/deployment.md to complete backup and migration inside a downtime window. That is a schema and data migration requirement, not a documentation gap. A platform holding PostgreSQL records, Milvus collections, Neo4j graphs and MinIO objects has state in four places, and a release that changes any of those shapes forces a coordinated migration. Teams without a maintenance window, or without a tested restore of those four stores, should treat every version bump as a project rather than a chore. The recent release cadence visible in the material (v0.7.2 in early September 2026, v0.7.1 in mid-July 2026, with a beta in between) means these bumps arrive often enough that the migration path is not a one-off event.

The knowledge graph is derived, not authored

Yuxi's graph capability is extraction from unstructured documents, not manual curation. The README describes parsing documents to run entity recognition and relationship extraction automatically, building a domain-specific graph, and reporting entity totals, relationship edge counts and build progress. Nodes can be searched by keyword, clicked for property details, and explored as a highlighted subgraph. Alongside that, the platform generates a multi-level knowledge map from knowledge base file metadata, which is a different artefact: a browsable structure of the corpus rather than a semantic network. The distinction is worth holding onto when evaluating fit. If your organisation already maintains an authoritative ontology or a curated graph, Yuxi's extractor will produce something adjacent to it rather than inside it, and the README does not describe an import path for an existing graph. If your knowledge lives in unstructured documents and nobody has time to build a schema by hand, extraction over chunks in Milvus is the reasonable starting point.

Where Yuxi is the wrong tool: single-tenant and read-only workloads

Five stateful services plus a worker queue is a real operational surface. PostgreSQL, Redis, MinIO, Milvus and Neo4j each need backup, monitoring and version attention, and the README's own upgrade warning shows what happens when one of them changes shape. For a single team with one corpus and no permission requirements, a plain vector store plus an embedding model covers the retrieval need with a fraction of the moving parts, and Yuxi's multi-tenant permission model, sandbox and approval cards are overhead you would be paying for without using. The sandbox deserves separate thought. The README describes an isolated filesystem where generated files are previewed and downloaded, and human approval cards that appear before operations that modify files or call high-risk external interfaces. That is a sensible design for agent-generated artefacts, but the isolation boundary is defined by the platform's own provisioner, and the README does not describe its guarantees in the material available here. If your threat model requires a specific container or VM escape resistance level, verify that yourself rather than assuming it from the word sandbox.

Alternatives and the actual difference in approach

Dify appears in the README, but as an external knowledge base service that Yuxi can connect to through a unified retriever, not as a replacement. The difference in approach is worth stating. Dify centres on application building: you compose a workflow or chat app, and knowledge is one component inside it. Yuxi centres on the knowledge layer itself, with graph extraction, chunk-level inspection, retrieval testing and an evaluation harness as first-class screens, and it treats agents as consumers of that layer. The README also lists Notion alongside Dify as a connectable external source, which reinforces the framing: Yuxi expects to sit in front of multiple knowledge backends rather than replace them. The practical consequence is that Yuxi's evaluation tooling is aimed at retrieval quality. The README describes building a benchmark question set, running batch evaluation, and outputting retrieval recall and answer relevance metrics, plus automatic generation of single-hop and multi-hop QA pairs. It also mentions using Langfuse Datasets to evaluate complete agent tasks. If your main uncertainty is whether retrieval is finding the right chunks, that instrumentation is the reason to pick Yuxi over a workflow-first tool.

Licence, maintenance surface and what to verify before you commit

Yuxi is MIT licensed, which permits commercial use and modification, and the licence identifier is stated in the repository metadata. That is permissive, and it also means no vendor is obligated to support your deployment; the maintenance burden is yours. Practically, the ongoing cost is the five backing services plus the document parsing engines (MinerU, PaddleX, RapidOCR), each of which has its own model weights and update cycle. The repository's default configuration tracks a specific tag, so pinning to v0.7.3 rather than main is the safer default, and the README's upgrade note means you should read docs/advanced/deployment.md before any version change rather than after. Verify three things first: that your model API is reachable from the Compose network for chat, embedding and rerank, since the README lists all three as configurable; that your backup procedure actually covers PostgreSQL, Milvus, Neo4j and MinIO together, because a partial restore will leave the graph and the vector index disagreeing; and that the sandbox provisioner's isolation meets your requirements, since the README describes its behaviour but not its guarantees.

Editorial conclusion

Adopt Yuxi if you need retrieval, graph extraction, agent orchestration and department-level permissions behind your own firewall and you are willing to run PostgreSQL, Redis, MinIO, Milvus and Neo4j alongside it. Do not adopt it if a single-tenant, single-process RAG library already covers your use case, or if you cannot schedule a maintenance window for upgrades. Before committing, clone the v0.7.3 tag, run ./scripts/init.sh, bring the stack up with docker compose up --build -d, confirm /api/system/ready returns ready, and then read docs/advanced/deployment.md to check what the v0.7.1 and v0.7.2 migration path requires on your data.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. xerrors/Yuxi on GitHub