LiveRAG

KO | EN

gitlite — search

#react #ai #typescript #llm #golang #go #machine-learning #rust #deep-learning #docker #macos #nodejs #java #cli

(★ 13)

LiveRAG personal knowledge-base voice agent

LiveRAG 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1>LiveRAG</h1>
  <p><strong>低延迟实时语音个人知识库助手</strong></p>
  <p>基于 LiveKit 实时语音与 LightRAG 知识库，快速搭建属于自己的个人语音 RAG Agent。</p>

---

## ✨ 项目简介

LiveRAG 是一个面向个人知识管理和实时语音问答的 RAG 应用。用户可以通过 WebUI 创建知识库、上传资料、配置语音模型，并在开始通话前选择一个知识库。通话过程中，Agent 会基于当前知识库进行实时检索和回答，同时记录命中文档、命中片段、检索耗时和回答依据。

一句话概括：**像语音助手一样自然，像知识库一样可信，并且足够快。**

## 🖼️ WebUI 预览

<table>
  <tr>
    <td width="50%" align="center">
      <img src="README.assets/实时语音.png" alt="LiveRAG 实时语音通话" width="100%" />
      <br />
      <sub>🎙️ 实时语音通话</sub>
    </td>
    <td width="50%" align="center">
      <img src="README.assets/知识库.png" alt="LiveRAG 知识库管理" width="100%" />
      <br />
      <sub>📚 知识库管理</sub>
    </td>
  </tr>
</table>

## 🚀 核心亮点

### 🎙️ 实时可打断语音交互

- 基于 LiveKit Agents 搭建 ASR、LLM、TTS 流式 Pipeline。
- 支持实时转录、流式生成、TTS 播放和用户随时打断。
- 无 RAG 场景端到端首响延迟约 **900ms**。

### 📚 个人知识库 RAG 闭环

- 集成 LightRAG，实现文档上传、解析、索引、删除、状态管理和检索增强问答。
- 支持返回命中文档、命中片段、检索耗时、cache 命中等结构化证据。
- 启用知识库检索后，端到端首响延迟约 **1500ms**。

### 🧱 单知识库隔离检索

- 每个知识库对应独立 LightRAG workspace。
- 原文件、SQLite 元数据、向量索引、图谱和 chunk 存储按 `kb_id` 隔离。
- 一次语音通话只能锁定一个知识库，通话中不允许切换，避免跨库污染和多库 fan-out 带来的延迟抖动。

### 🧠 上下文与长期记忆

- 通话开始前一次性渲染固定 `SessionSystemPrompt`。
- 上下文由 `SOUL.md`、当前知识库 `history.jsonl`、`knowledge_overview.md` 和 RAG 工具规则组成。
- 通话中不再每轮动态拼接大段上下文，只保留当前 LiveKit messages、当前用户输入和可选工具结果。
- 挂断后使用独立 Context Model 压缩本次会话，写入当前知识库隔离的 history。

### 🎛️ 多模型多音色配置

- 支持通过 WebUI 配置语音 LLM、ASR、TTS provider、模型和音色。
- 当前链路支持豆包 ASR、Qwen/DashScope 兼容 LLM、MiniMax TTS、DashScope Realtime TTS。
- 模型配置写入本地运行时配置，挂断后重新接通即可生效。

### 📦 统一 API 与 Docker 部署

- FastAPI 作为唯一管理 API 入口。
- 统一暴露知识库、会话、模型、Prompt、RAG 查询和运行态接口。
- Docker Compose 可同时启动 LiveKit Server、RAG Core、管理 API、Agent 和前端。

## 🧩 技术栈

| 模块 | 技术 |
| --- | --- |
| 实时语音 | LiveKit Server, LiveKit Agents |
| 后端 API | FastAPI, Uvicorn, Python |
| RAG 引擎 | LightRAG, per-KB workspace |
| 元数据 | SQLite, local file storage |
| 语音模型 | 豆包 ASR, Qwen/DashScope LLM, MiniMax TTS, DashScope Realtime TTS |
| 上下文模型 | OpenAI-compatible large model |
| 前端 | Next.js, LiveKit Agents UI |
| 部署 | Docker, Docker Compose, Nginx 可选 |

## 🏗️ 系统架构

```mermaid
flowchart LR
  User[用户 / WebUI] --> Next[Next.js 前端]
  Next --> API[LiveRAG 管理 API]
  Next --> LK[LiveKit Server]
  Agent[LiveKit Agent] --> LK
  Agent --> API
  API --> Core[RAG Core Service]
  Core --> Engine[LightRAG Engine]
  Engine --> KB[(单知识库 Workspace)]
  API --> DB[(SQLite 元数据)]
  Agent --> ASR[ASR Provider]
  Agent --> LLM[Voice LLM]
  Agent --> TTS[TTS Provider]
  API --> ContextLLM[Context Model]
```

## 📁 项目结构

```text
LiveRAG/
  liverag/
    agent/          # LiveKit Agent、语音 provider、RAG tool、延迟日志
    api/            # FastAPI 管理 API 和 RAG gateway
    context/        # SOUL、history、overview、SessionSystemPrompt 渲染
    rag/            # LightRAG engine manager、知识库元数据、RAG Core API
    runtime/        # 运行态路径和本地状态
  docs/             # API、架构、RAG、history 文档
  README.assets/    # README 封面和 WebUI 截图
  docker-compose.yml
  Dockerfile
  pyproject.toml
```

默认运行数据存储在：

```text
~/.LiveRAG/
  liverag.db
  prompts/
    system_prompt_template.md
    SOUL.md
    history_compress_prompt.md
    knowledge_overview_prompt.md
  history/{kb_id}/history.jsonl
  context/{kb_id}/knowledge_overview.md
  session/messages.jsonl
  session/rag_context.jsonl
  session/session_system_prompt.md
  model/config.json
  rag/knowledge_bases/{kb_id}/
    sources/{document_id}/{original_filename}
    storage/
    logs/
```

## ⚡ 快速开始

### 1. 准备环境

```bash
git clone <your-liverag-repo-url>
cd LiveRAG
uv sync
cp .env.example .env.local
```

编辑 `.env.local`，填入 LiveKit、ASR、LLM、TTS、RAG 和 Context Model 配置：

```bash
LIVEKIT_URL=ws://127.0.0.1:7880
LIVEKIT_API_KEY=my-dev-key
LIVEKIT_API_SECRET=my-dev-secret

VOLCENGINE_STT_APP_ID=...
VOLCENGINE_STT_ACCESS_TOKEN=...

VOICE_LLM_MODEL=qwen-flash
VOICE_LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
VOICE_LLM_API_KEY=...

DASHSCOPE_API_KEY=...
MINIMAX_API_KEY=...

LIVERAG_USER_DATA_DIR=~/.LiveRAG
LIVERAG_API_PORT=9821
LIGHTRAG_TOOL_MODE=auto
```

### 2. 启动本地后端

启动 LiveKit Server：

```bash
brew install livekit
LIVEKIT_KEYS="my-dev-key: my-dev-secret" livekit-server --dev
```

启动 RAG Core Service：

```bash
uv run liverag-rag-service
```

启动管理 API：

```bash
uv run liverag-api
```

启动 LiveKit Agent：

```bash
uv run python -m liverag.main dev
```

### 3. 启动前端

前端位于当前仓库的 `frontend/` 目录：

```bash
cd frontend
pnpm install
pnpm exec next dev --turbopack -p 3001
```

访问：

```text
http://127.0.0.1:3001
```

### 4. 健康检查

```bash
curl http://127.0.0.1:9821/health
curl http://127.0.0.1:9821/rag/knowledge-bases
curl http://127.0.0.1:9721/v1/readyz
```

## 🐳 Docker Compose

```bash
cp .env.example .env.local
# 修改 .env.local

docker compose --env-file .env.local build
docker compose --env-file .env.local up -d
```

Compose 默认包含：

- `livekit`：LiveKit Server
- `liverag-rag`：内部 LightRAG Core Service
- `liverag-api`：统一管理 API
- `liverag-agent`：LiveKit Agent Worker
- `liverag-frontend`：Next.js WebUI

> `docker-compose.yml` 使用当前仓库的 `frontend/` 目录构建 WebUI。

## 🔌 核心 API

LiveRAG 默认只对前端暴露一个管理 API 端口：`9821`。

| 功能 | API |
| --- | --- |
| 健康与运行态 | `GET /health`, `GET /runtime/state` |
| 知识库 | `GET/POST /rag/knowledge-bases`, `GET/PATCH/DELETE /rag/knowledge-bases/{kb_id}` |
| 文档 | `GET /rag/knowledge-bases/{kb_id}/documents`, `POST /rag/knowledge-bases/{kb_id}/documents/files`, `POST /rag/knowledge-bases/{kb_id}/documents/text` |
| 查询 | `POST /rag/knowledge-bases/{kb_id}/query/context`, `POST /rag/session-query/context` |
| 会话 | `GET /session/turns`, `GET /session/rag-context`, `GET/PUT /session/knowledge-base`, `POST /session/clear` |
| Prompt | `GET/PUT /prompt/soul`, `GET /rag/knowledge-bases/{kb_id}/context/overview` |
| 模型 | `GET/PUT /model/config`, `GET /model/options`, `GET/PUT /model/context-config` |

完整接口见 [docs/API.md](./docs/API.md)。

## 🧠 上下文设计

通话开始前只渲染一次固定系统提示词：

```text
SessionSystemPrompt =
  system_prompt_template.md
  + SOUL.md
  + 当前知识库 history.jsonl
  + 当前知识库 knowledge_overview.md
  + RAG 工具描述，仅 rag_tool_mode=auto 时启用
```

通话中模型只接收：

```text
固定 SessionSystemPrompt
+ 当前 LiveKit messages
+ 当前用户输入
+ 可选 tool call / tool result
```

这个设计避免每一轮都重建大上下文，有利于降低延迟和保持行为稳定。

## 📚 知识库隔离规则

- 一次通话只锁定一个知识库。
- 查询不会同时查多个知识库。
- 文档原文件、SQLite 元数据、LightRAG storage 和日志按 `kb_id` 隔离。
- 回答依据包含 `kb_id`、`kb_name`、`document_id`、`file_path`、`score`、`content_preview`。

## 📈 性能目标

| 场景 | 端到端首响延迟 |
| --- | --- |
| 不使用 RAG | 约 900ms |
| 使用 RAG | 约 1500ms |

实际延迟取决于 ASR/TTS provider、LLM TTFT、网络质量和当前知识库 engine 是否预热。

## 🛠️ 开发检查

```bash
uv run ruff check liverag
uv run python -m compileall liverag
```

常用运行态文件：

```text
~/.LiveRAG/session/runtime_state.json
~/.LiveRAG/session/messages.jsonl
~/.LiveRAG/session/rag_context.jsonl
~/.LiveRAG/logs/
```

## 📖 文档

- [API 文档](./docs/API.md)
- [架构说明](./docs/ARCHITECTURE.md)
- [RAG 设计](./docs/RAG.md)
- [History / Memory 设计](./docs/MEMORY.md)
- [LiveKit Server 部署](./docs/LiveKit-Server部署.md)

## 📄 License

本项目基于 [MIT License](./LICENSE) 发布。

LiveRAG

LiveRAG 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

LiveRAG

LiveRAG 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README