DOCSEARCHbyAlgolia
Submit Docs

Yuxi Documentation

repository·main·Indexed 27 days ago

https://github.com/xerrors/yuxi

Yuxi is a multi-tenant development platform for building intelligent knowledge bases and knowledge graph agents. It integrates RAG, Milvus-based graph storage, and LangGraph orchestration. The platform features a Vue 3 frontend, FastAPI backend, and ARQ worker system, supporting advanced reasoning with cited sources and MCP (Model Context Protocol). It includes the yuxi-cli for remote management, knowledge base uploads, and agent evaluations.

Tokens
28.9K
Snippets
38
Records
205
Agent score
91%

What's inside Yuxi

  2. Overview of Yuxi (语析) Platform

    main

    Yuxi is an intelligent knowledge base and knowledge graph Agent development platform designed to build production-grade AI applications that combine Retrieval-Augmented Generation (RAG) with knowledge graph reasoning. It provides orchestration for agents, knowledge retrieval, graph reasoning, tool calling, and file system capabilities.

    Core Capabilities

    • Agent Development: Based on LangGraph, it offers a configurable and extensible framework for configuring models, prompts, tools, MCP, Skills, sub-agents, and middleware.
    • Integrated RAG: Provides a complete pipeline for document ingestion, including parsing, chunking, vectorization, and retrieval configuration.
    • Knowledge Graph Reasoning: Integrates with Milvus and Neo4j to extract entities and relationships from ingested chunks, enabling hybrid retrieval (RRF) that combines vector search with graph triples.
    • Document Understanding: Supports multi-format parsing (PDF, Office, Markdown, images) using MinerU, PaddleX, and RapidOCR to ensure structured data entry.

  3. Overview of Yuxi Agent Platform

    main

    Yuxi is a multi-tenant agent platform designed to make enterprise knowledge retrievable, reasoned over, and deliverable by agents. It unifies RAG (Retrieval-Augmented Generation) retrieval, Milvus-backed in-knowledge-base graphs, and LangGraph multi-agent orchestration.

    Key capabilities include:

    • Agent Development: Built on LangGraph with support for SubAgents, Skills, MCPs, Tools, and asynchronous background workers.
    • Knowledge Base (RAG): Multi-format document parsing (MinerU, PaddleX, OCR) with configurable Embedding and Rerank models.
    • Knowledge Graph: Entity-relation graph construction and visualization within Milvus knowledge bases.
    • Multi-tenancy: User and department-level access control and API Key authentication.
    • Platform Architecture: Vue 3 frontend and FastAPI backend.

  4. Overview of yuxi-cli

    main

    The yuxi-cli is the command line client for Yuxi. It provides tools for remote management, server discovery, knowledge base management, and running agent evaluations.

    Key capabilities include:

    • Remote management via ~/.yuxi/config.toml.
    • Browser-based login and API key imports.
    • Knowledge base file uploads using yuxi kb upload.
    • Running Langfuse dataset experiments with yuxi agent eval.

  5. Overview of Yuxi (语析)

    main

    Yuxi is an AI-powered intelligent knowledge base and knowledge graph agent development platform. It integrates RAG (Retrieval-Augmented Generation), Milvus-based knowledge graph storage, and LangGraph multi-agent orchestration into a unified multi-tenant workspace.

    Key features include:

    • Admin Configuration: Manage knowledge bases, models, and permissions.
    • Agent Interaction: A ChatGPT-like interface for interacting with agents equipped with Skills, MCP (Model Context Protocol), sub-agents, and sandbox tools.
    • Advanced Reasoning: Provides answers with cited sources, knowledge graph reasoning, and deliverable outputs.

  6. Understand Langfuse data mapping in Yuxi

    main

    When Langfuse is integrated, Yuxi maps internal entities to Langfuse concepts as follows to allow for unified tracing across user, thread, and agent dimensions:

    • User: Mapped to Langfuse user_id.
    • Conversation Thread: Mapped to Langfuse session_id.
    • Agent Execution: Each user input that triggers an agent execution forms an independent trace.

    This mapping allows you to view model inputs/outputs, tool call chains, latency, and errors within a single trace, or analyze continuous multi-turn conversations within the same session.

  7. Understand the Yuxi testing hierarchy

    main

    Yuxi tests are organized into three distinct layers to balance speed and coverage. Choose the appropriate layer based on the scope of your test:

    1. Unit Tests (backend/test/unit): Pure logic tests that do not depend on running Docker services. Use monkeypatch, fake repositories, stubs, or tmp_path.
    2. Integration Tests (backend/test/integration): Tests that verify real API behavior. These require a running environment via docker compose up -d and validate authentication, permissions, parameters, and side effects through actual HTTP interfaces.
    3. E2E Tests (backend/test/e2e): End-to-end tests for critical paths (e.g., run, viewer, attachments, file persistence). These are fewer in number and slower to execute.

  8. Understand the Yuxi System Architecture

    main

    Yuxi is a knowledge base platform designed for RAG (Retrieval-Augmented Generation), knowledge graphs, and multi-agent workflows. The system architecture consists of a Vue 3 frontend, a FastAPI backend, and an ARQ-based worker system.

    Core Components:

    • Frontend (web-dev): Vue 3 / Vite application for managing agents, knowledge bases, models, tools, Skills, MCP, and SubAgents.
    • API Service (api-dev): FastAPI service handling HTTP requests via /api.
    • Worker Service (worker-dev): ARQ worker that executes dispatched AgentRun tasks and handles exception recovery.
    • Sandbox Provisioner: Provides isolated sandboxes for executing agent tools.
    • Data Layer:
      • PostgreSQL: Business data, knowledge base metadata, request queues, AgentRun states, and LangGraph checkpoints.
      • Redis: ARQ task delivery, running events, cancellation signals, and model caching.
      • MinIO: Attachments, raw knowledge base files, and other object data.
      • Milvus/Etcd: Vector retrieval and metadata coordination.
      • Neo4j: Knowledge graph storage.

  9. Understand the Yuxi configuration hierarchy

    main

    Yuxi uses a multi-layered configuration architecture. Configuration values are resolved in the following order of precedence (from lowest to highest):

    1. Code Defaults: Hardcoded values in the source code.
    2. TOML Files: Settings stored in saves/config/base.toml.
    3. Environment Variables: System-level environment variables.

    Note that Model Configuration is managed separately via the web interface and is not part of this hierarchy.

  10. Set up MinerU (High Precision) via Docker

    main

    MinerU is built-in via the mineru-api service in the all docker-compose profile. It requires a GPU. The service provides a /file_parse interface on port 30001.

    To start the service:

    docker compose --profile all up -d --build mineru-api

    Note: The backend api and worker connect via MINERU_API_URI=http://mineru-api:30001 by default. If you encounter out-of-memory errors, you can adjust the --gpu-memory-utilization parameter in docker-compose.yml.

  11. Create and manage API Keys

    main

    Yuxi provides an API Key authentication mechanism for automated system-to-system calls. API Keys are prefixed with yxkey_ and are bound to the user who created them, inheriting that user's permissions.

    Key Management via API

    The following endpoints are used to manage API Keys using standard authentication:

    • GET /api/user/apikey/: List API Keys visible to the current user.
    • POST /api/user/apikey/: Create a new API Key. Note: The full secret is only displayed once upon creation. Save it immediately.
    • PUT /api/user/apikey/{api_key_id}: Update name, status, or expiration time.
    • DELETE /api/user/apikey/{api_key_id}: Delete a key.

    Security Best Practices

    • HTTPS is mandatory in production: API Keys are sent in plaintext in the Authorization header. Always use https://<your-domain> to prevent interception.
    • Avoid hardcoding: Use environment variables or configuration centers to manage keys.
    • Rotation: Use the expiration feature to set short lifespans and rotate keys regularly.
    • Isolation: Create unique API Keys for different external systems to limit the blast radius if one is compromised.

  12. Configure OCR methods and settings

    main

    Administrators can manage OCR settings via Settings → OCR Configuration. You can set a global default OCR method and configure endpoints or credentials for self-hosted or cloud services.

    Configuration Behavior:

    • Settings are stored in the config_options table.
    • The system prioritizes database values; if a database field is empty, it falls back to the corresponding environment variable.
    • To clear a database value and revert to using an environment variable, leave the configuration field empty and save.
    • Sensitive fields (like API keys) are masked in the UI and will not be echoed back in plain text by the reading interface.