Upload folder using huggingface_hub

6b62834 verified 9 days ago

29.3 kB

	# Agentic RAG 智能问答系统

	<p align="center"><b>ReAct Agent 驱动</b> \| <b>多模态知识库</b> \| <b>MCP 工具扩展</b> \| <b>边缘/本地部署</b></p>

	---

	基于 ReAct Agent 的多模态检索增强生成（RAG）系统，支持文本、图片、音频、视频的统一入库与跨模态检索，提供智能问答、工具调用、MCP 扩展、流式对话、语音交互等完整能力。支持 OpenAI / 本地 OpenAI-compatible 模型，可灵活部署在云端或边缘设备上。

	[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
	[![FastAPI](https://img.shields.io/badge/FastAPI-0.115%2B-009688.svg)](https://fastapi.tiangolo.com/)
	[![React 19](https://img.shields.io/badge/React-19-61DAFB.svg)](https://react.dev/)
	[![Milvus Lite](https://img.shields.io/badge/Vector%20Store-Milvus%20Lite-orange.svg)](https://milvus.io/)
	[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)

	> 当前版本：`0.1.0`。部分能力还需要进一步开发验证。
	>
	---

	![alt text](image.png)

	![alt text](image-1.png)

	---

	## 目录

	- [项目背景](#项目背景)
	- [核心特性](#核心特性)
	- [系统架构](#系统架构)
	- [快速开始](#快速开始)
	- [使用方式](#使用方式)
	- [其他功能](#其他功能)
	- [多模态知识库](#多模态知识库)
	- [MCP 工具扩展](#mcp-工具扩展)
	- [语音与消息网关](#语音与消息网关)
	- [功能状态](#功能状态)
	- [AX8850 运行示例](#ax8850-运行示例)


	---

	## 项目背景

	### 为什么需要 Agentic RAG？

	传统 RAG 系统只能被动检索，而现实场景中的问题往往需要多步推理、工具调用和动态决策：

	- 静态检索局限 — 一次性检索难以回答需要多轮推理的复杂问题。
	- 模态割裂 — 文本、图片、音视频分散存储，无法统一检索，大量非文本信息被浪费。
	- 工具孤岛 — 检索、计算、外部 API 等能力各自独立，Agent 无法根据上下文自主选择工具。
	- 部署复杂 — 多数方案依赖云端服务，存在隐私泄露风险和高昂调用成本。

	### 本项目的解决思路

	本项目将 ReAct Agent 与多模态 RAG 深度融合，让 Agent 能够"思考→行动→观察→再思考"，在推理过程中自主决定何时检索知识库、何时调用外部工具、何时生成最终答案：

	- 🧠 Agent 驱动检索 — Agent 根据问题复杂度自主决定检索策略，支持多轮推理和工具链调用。
	- 🔗 MCP 生态接入 — 通过 Model Context Protocol 接入外部工具，Agent 能力可无限扩展。
	- 🎨 多模态统一 — 文本、图片、音频、视频统一向量空间，跨模态语义检索。
	- 🏠 本地优先 — 支持本地 LLM / Embedding 服务，数据不出设备，隐私安全可控。

	### 应用场景

	\| 领域 \| 典型场景 \| 核心价值 \|
	\|------\|----------\|----------\|
	\| 🏢 企业知识管理 \| 智能客服、内部培训、文档问答 \| 多轮对话理解上下文，自动调用内部工具查询数据 \|
	\| 🔬 研发辅助 \| 代码库问答、技术文档检索、API 集成 \| Agent 自主检索代码示例、调用调试工具、生成修复建议 \|
	\| 📚 教育科研 \| 文献综述、课件问答、实验数据分析 \| 跨文献多轮推理，自动提取关键信息并生成综述 \|
	\| 🎬 内容创作 \| 素材检索、脚本生成、多模态内容理解 \| 以文搜图/以图搜视频，Agent 辅助创作全流程 \|
	\| 🏥 专业领域 \| 医疗文献问答、法律条文检索、金融报告分析 \| 严格的数据隐私要求下本地运行，专业工具链集成 \|

	---

	## 核心特性

	### 🚀 功能特性

	- ReAct Agent 引擎 — 支持 `Thought → Action → Observation → Final Answer` 循环，以及原生 Function Calling，Agent 可自主规划多步推理。
	- 多模式智能路由 — 按查询意图动态装配工具集（知识库检索、联网搜索、媒体理解及 MCP 扩展工具），Agent 每轮推理均可自主调用工具。
	- 四模态统一检索 — 文本、图片、音频、视频在同一向量空间中表示，支持以文搜图、以图搜视频等跨模态查询。
	- 混合检索策略 — 支持 `naive` 纯向量检索和 `hybrid` 向量 + 知识图谱混合检索，提升召回准确率。
	- 流式对话体验 — REST SSE 与 WebSocket 双通道流式输出，实时展示 Agent 思考过程和工具调用。
	- 多入口灵活接入 — Web UI、REST API、WebSocket、CLI、异步 Python SDK，满足不同场景需求。

	### 🔧 技术特性

	- MCP 工具扩展 — 启动时自动连接外部 MCP Server，将工具注册到 Agent，实现能力热插拔。
	- 多提供商 LLM — 内置 OpenAI、以及任意 OpenAI-compatible 本地服务适配。
	- 模块化架构 — Agent 引擎、知识管线、向量存储、LLM 服务、记忆系统分层解耦，可独立替换升级。
	- 本地数据持久化 — SQLite 会话存储、Milvus Lite 向量库、JSON 知识图谱，零外部依赖即可运行。
	- 可配置预处理 — 文本分块大小、图片处理策略、音频切片参数等均可通过环境变量调节。

	---

	## 系统架构

	### 整体架构

	```text
	┌─────────────────────────────────────────────────────────────┐
	│ 接入层 (Entry Points) │
	│ Web UI │ REST API │ WebSocket │ CLI │ Python SDK │
	└──────────────────────────┬──────────────────────────────────┘
	│
	▼
	┌─────────────────────────────────────────────────────────────┐
	│ Agent 路由与引擎层 │
	│ AgentRouter (模式路由) + ReActEngine (推理循环) │
	│ ↓ Thought → Action → Observation ↑ │
	└──────────────────────────┬──────────────────────────────────┘
	│
	┌───────────────┼───────────────┐
	▼ ▼ ▼
	┌─────────┐ ┌──────────┐ ┌──────────┐
	│ RAG 工具 │ │ MCP 工具 │ │ 媒体工具 │
	│(知识库) │ │(外部扩展)│ │(语音/图像)│
	└────┬────┘ └──────────┘ └──────────┘
	│
	▼
	┌─────────────────────────────────────────────────────────────┐
	│ 知识管线 (Knowledge Pipeline) │
	│ Parse → Process → Embed → Milvus Lite │
	│ └────────→ Knowledge Graph (可选) │
	└─────────────────────────────────────────────────────────────┘

	┌─────────────────────────────────────────────────────────────┐
	│ 数据持久化层 │
	│ SQLite (会话/消息) │ Milvus Lite (向量) │ JSON (KG) │
	└─────────────────────────────────────────────────────────────┘
	```

	### 知识管线流程

	```text
	原始输入 (文本/图片/音频/视频/PDF/Office)
	│
	▼
	┌───────────────┐
	│ 统一解析层 │ → ContentList (统一内容表示)
	│ Parse │
	└───────┬───────┘
	│
	▼
	┌───────────────┐
	│ 模态处理层 │ → 文本分块 / 图片处理 / 音频切片 / 视频帧提取
	│ Process │
	└───────┬───────┘
	│
	▼
	┌───────────────┐ ┌───────────────┐
	│ 向量化层 │ ──→ │ 知识图谱层 │ (可选，enable_kg=true)
	│ Embed │ │ KG Builder │
	└───────┬───────┘ └───────────────┘
	│
	▼
	┌───────────────┐
	│ 向量存储层 │ → Milvus Lite (本地持久化)
	│ Vector Store │
	└───────────────┘
	```

	### Agent 推理流程

	```text
	用户问题
	│
	▼
	┌─────────────┐
	│ AgentRouter│
	└──────┬──────┘
	│
	▼
	┌────────────────────────────────────────┐
	│ ReAct 推理循环 │
	│ ┌─────────┐ ┌─────────┐ ┌────────┐ │
	│ │ Thought │ → │ Action │ → │Observe │ │
	│ │ (思考) │ │ (行动) │ │ (观察) │ │
	│ └─────────┘ └─────────┘ └────────┘ │
	│ ↑ │ │
	│ └───────────────────────────┘ │
	│ (最多 N 轮) │
	└────────────────────────────────────────┘
	│
	▼
	┌─────────────┐
	│ Final Answer │ → 生成最终回答，附来源引用
	└─────────────┘
	```



	### 项目结构

	```text
	Agentic_RAG/
	├── agentic_rag/ # 后端核心代码
	│ ├── agent/ # ReAct 引擎、Prompt 模板、模式路由
	│ ├── config/ # Pydantic Settings、默认配置
	│ ├── core/ # MCP 客户端、多模态处理、STT/TTS
	│ ├── data/ # 数据模型、SQLite Repository
	│ ├── entrypoints/ # 接入层
	│ │ ├── rest/ # FastAPI REST API
	│ │ ├── websocket/ # WebSocket 服务
	│ │ ├── cli/ # 命令行接口
	│ │ ├── sdk/ # Python SDK
	│ │ └── gateway/ # 消息平台网关
	│ ├── orchestration/ # L1 工具、L2 能力编排
	│ ├── runtime/ # 运行时上下文、流总线、轮次协调
	│ ├── services/ # LLM、知识管线、记忆、会话、向量存储
	│ └── utils/ # 通用工具
	├── frontend/ # React 19 + Vite 8 前端
	│ ├── src/
	│ └── vite.config.js
	├── static/ # 前端构建产物（生产模式）
	├── tests/ # 测试
	│ ├── unit/ # 单元测试
	│ ├── integration/ # 集成测试
	│ └── dir/ # 测试数据
	├── scripts/ # 辅助脚本（预留）
	├── data/ # SQLite 运行时数据
	├── workspace/ # 上传文件、向量库、知识图谱
	├── .env # 环境变量配置（由 .env.example 复制）
	├── .env.example # 环境变量模板
	├── mcp_servers.json # MCP 配置（JSON）
	├── mcp_servers.yaml # MCP 配置（YAML）
	├── pyproject.toml # Python 项目配置
	└── README.md
	```

	---

	## 快速开始

	### 1. 环境要求

	- Python 3.10+
	- Node.js 18+（构建 Web UI 需要；生产环境直接使用已构建的 `static/` 产物时可省略）


	### 2. 安装

	```bash
	git clone <repository-url>
	cd Agentic_RAG

	python -m venv .venv
	source .venv/bin/activate # Linux/macOS
	# .venv\Scripts\activate # Windows PowerShell

	python -m pip install --upgrade pip
	pip install -e ".[dev]"

	# 完整安装：Anthropic、语音、视频、文档解析和消息网关
	# pip install -e ".[dev,anthropic,voice,media,documents,gateways]"

	# 可选：PDF/Office 完整解析
	pip install pymupdf # PDF 文本提取及 OCR 页面渲染
	# 或按 Docling 官方说明安装 docling
	```


	### 3. 配置环境变量

	从模板创建 `.env` 文件：

	```bash
	cp .env.example .env
	```

	然后按需修改（配置使用无前缀变量名）：

	```bash
	# ============ LLM 配置 ============
	DEFAULT_PROVIDER=local

	LLM_PROVIDERS__LOCAL__API_BASE=http://localhost:8009/v1
	LLM_PROVIDERS__LOCAL__MODEL=your-chat-model
	LLM_PROVIDERS__LOCAL__API_KEY=not-needed
	LLM_PROVIDERS__LOCAL__VISION_MODEL=your-vision-model

	# ============ Embedding 配置 ============
	EMBEDDING__PROVIDER=local
	EMBEDDING__API_BASE=http://localhost:8010/v1
	EMBEDDING__API_KEY=not-needed
	EMBEDDING__MODEL=your-embedding-model
	EMBEDDING__DIM=768
	EMBEDDING__BATCH_SIZE=4

	# ============ 向量库配置 ============
	MILVUS__DIM=768

	# ============ API 服务配置 ============
	API__HOST=0.0.0.0
	API__PORT=8007
	```

	> ⚠️ `EMBEDDING__DIM` 与 `MILVUS__DIM` 必须一致。若需修改已创建集合的维度，请先备份并删除旧的 `workspace/milvus_lite.db`，再重新建库。

	使用官方云服务：

	```bash
	# OpenAI
	DEFAULT_PROVIDER=openai
	LLM_PROVIDERS__OPENAI__API_KEY=your-openai-api-key
	LLM_PROVIDERS__OPENAI__API_BASE=https://api.openai.com/v1
	LLM_PROVIDERS__OPENAI__MODEL=gpt-4o

	# Anthropic Claude（Embedding 仍需单独配置）
	DEFAULT_PROVIDER=claude
	LLM_PROVIDERS__CLAUDE__API_KEY=your-anthropic-api-key
	LLM_PROVIDERS__CLAUDE__API_BASE=https://api.anthropic.com
	LLM_PROVIDERS__CLAUDE__MODEL=your-claude-model
	```

	### 4. 构建前端

	```bash
	cd frontend
	npm run build
	cd ..
	```

	Vite 产物输出到 `static/`，FastAPI 挂载 `/static` 并在 `/` 返回 SPA 首页。生产环境只需构建一次；前端源码未改动时无需重复执行。

	### 5. 启动服务

	```bash
	# 生产模式
	python -m agentic_rag serve --host 0.0.0.0 --port 8007

	# 开发模式（自动重载）
	python -m agentic_rag serve --port 8007 --reload
	# 或
	uvicorn agentic_rag.entrypoints.rest.app:app --host 0.0.0.0 --port 8007 --reload
	```

	### 6. 验证运行

	```bash
	curl http://localhost:8007/health
	curl http://localhost:8007/ready
	```

	\| 地址 \| 说明 \|
	\|------\|------\|
	\| `http://localhost:8007/` \| Web UI 主界面 \|
	\| `http://localhost:8007/docs` \| Swagger API 文档 \|
	\| `http://localhost:8007/health` \| 进程健康检查 \|
	\| `http://localhost:8007/ready` \| LLM 配置就绪检查 \|

	✅ 打开 `http://localhost:8007/`，看到聊天界面即部署成功。若页面空白或报资源加载失败，通常是 `static/` 缺失或过期，请回到第 4 步重新执行 `npm run build`。

	---

	## 使用方式

	系统提供多种使用入口：Web UI 是浏览器中的完整交互界面，适合直接使用；CLI / REST API / WebSocket / Python SDK 面向脚本调用与二次开发。

	### Web UI

	```bash
	# 1. 构建前端（首次或前端有更新时执行）
	cd frontend && npm install && npm run build && cd ..

	# 2. 启动服务（后端托管 Web UI）
	python -m agentic_rag serve --port 8007
	```

	启动后在浏览器打开 `http://localhost:8007/`：

	- 对话交互 — 输入问题即开始问答，流式展示 Agent 的 Thought / Action / Observation 推理过程
	- 文件上传 — 上传文本、图片、音频、视频入库，对应 `/api/v1/rag/upload`
	- 会话管理 — 多会话切换，历史记录持久化在本地 SQLite


	### CLI 命令行

	```bash
	# 普通问答
	python -m agentic_rag chat "什么是 RAG？"

	# 自动路由或指定模式
	python -m agentic_rag chat --mode research "深入总结知识库中的检索方法"

	# 流式输出
	python -m agentic_rag chat --stream "解释 ReAct 的执行过程"

	# 指定已配置的 Provider
	python -m agentic_rag chat --provider local "你好"

	# 文本文件入库
	python -m agentic_rag ingest --file document.txt --source cli

	# 查看当前配置信息
	python -m agentic_rag info

	# 查看帮助
	python -m agentic_rag --help
	```

	### REST API

	#### 非流式聊天

	```bash
	curl -X POST http://localhost:8007/api/v1/chat \
	-H 'Content-Type: application/json' \
	-d '{"message":"什么是 RAG？","mode":"auto"}'
	```

	#### SSE 流式聊天

	```bash
	curl -N -X POST http://localhost:8007/api/v1/chat/stream \
	-H 'Content-Type: application/json' \
	-d '{"message":"检索知识库中的向量数据库资料","mode":"research"}'
	```

	主要事件类型：`text_delta`、`tool_call_start`、`tool_call_result`、`error`、`done`。

	#### 知识库检索

	```bash
	curl -X POST http://localhost:8007/api/v1/rag/search \
	-H 'Content-Type: application/json' \
	-d '{"query":"向量数据库","top_k":5,"mode":"hybrid"}'
	```

	#### 文本入库

	```bash
	curl -X POST http://localhost:8007/api/v1/rag/ingest \
	-H 'Content-Type: application/json' \
	-d '{"content":"Milvus 是一个向量数据库。","source":"manual"}'
	```

	#### 文件/多模态上传

	```bash
	curl -X POST http://localhost:8007/api/v1/rag/upload \
	-F 'file=@document.pdf' \
	-F 'source=manual-upload' \
	-F 'ingest_mode=multimodal' \
	-F 'mm_method=pure' \
	-F 'enable_kg=true'
	```

	支持的文件格式：
	- 文本/文档：`.txt` `.md` `.json` `.yaml` `.csv` `.py` `.html` `.pdf` `.docx`
	- 图片：`.jpg` `.png` `.gif` `.webp` `.bmp` `.svg`
	- 视频：`.mp4` `.avi` `.mov` `.mkv` `.webm`
	- 音频：`.mp3` `.wav` `.m4a` `.ogg` `.flac`

	#### 会话管理

	```bash
	# 创建会话（user_id 是查询参数）
	curl -X POST 'http://localhost:8007/api/v1/session?user_id=user123'

	# 获取会话列表
	curl 'http://localhost:8007/api/v1/sessions?user_id=user123'

	# 获取会话消息
	curl http://localhost:8007/api/v1/session/<session_id>/messages

	# 删除会话
	curl -X DELETE http://localhost:8007/api/v1/session/<session_id>
	```


	### WebSocket

	```javascript
	const sessionId = crypto.randomUUID()
	const ws = new WebSocket(`ws://localhost:8007/ws/${sessionId}`)

	ws.addEventListener('open', () => {
	ws.send(JSON.stringify({
	type: 'chat',
	payload: {
	message: '检索知识库中的 ReAct 资料',
	mode: 'research',
	},
	}))
	})

	ws.addEventListener('message', (event) => {
	const message = JSON.parse(event.data)
	console.log(message.type, message.data)
	})
	```

	### Python SDK

	```python
	import asyncio
	from agentic_rag.entrypoints.sdk.client import AgenticRAGClient


	async def main() -> None:
	async with AgenticRAGClient("http://localhost:8007") as client:
	# 非流式聊天
	response = await client.chat("什么是 RAG？", mode="auto")
	print(response["answer"])

	# 流式聊天
	async for event in client.chat_stream("检索知识库"):
	print(event)

	# 文本入库
	result = await client.rag_ingest(
	"这是一段需要写入知识库的文本。",
	source="sdk",
	)
	print(result)


	asyncio.run(main())
	```

	---

	## 其他功能

	### 多模态知识库

	#### 入库模式

	`/api/v1/rag/upload` 参数说明：

	\| 参数 \| 默认值 \| 说明 \|
	\|------\|--------\|------\|
	\| `ingest_mode` \| `multimodal` \| `text` 跳过媒体项；`multimodal` 处理媒体项 \|
	\| `mm_method` \| `pure` \| `pure` / `caption` / `both` \|
	\| `chunk_size` \| `512` \| 文本分块字符数 \|
	\| `chunk_overlap` \| `50` \| 分块重叠字符数 \|
	\| `enable_kg` \| `false` \| 构建并持久化知识图谱 \|

	`mm_method` 说明：
	- `pure` — 直接构造多模态 Embedding 输入；纯文本 Embedding API 会退化为占位文本
	- `caption` — 使用视觉模型生成图片描述，再对描述文本做 Embedding
	- `both` — 同时使用原始媒体和描述文本

	#### 本地数据

	运行时产生的数据文件：

	```text
	data/agentic_rag.db # 会话与消息历史
	workspace/milvus_lite.db # Milvus Lite 向量数据库
	workspace/knowledge_graph.json # 知识图谱（启用 KG 时）
	workspace/uploads/ # 上传文件缓存
	```

	> 🔒 这些文件可能包含用户内容或模型数据，部署时请配置合适的访问控制、备份和清理策略。

	### MCP 工具扩展

	项目支持通过 Model Context Protocol (MCP) 接入外部工具，Agent 可自动发现并使用这些工具。

	#### 配置方式

	按优先级查找配置：

	1. `mcp_servers.json`
	2. `mcp_servers.yaml`
	3. MCP 环境变量

	推荐使用不含密钥的配置文件，通过环境变量提供凭据：

	```json
	{
	"mcpServers": {
	"example-search": {
	"command": "npx",
	"args": ["-y", "example-search-mcp"],
	"disabled": false
	}
	}
	}
	```

	```bash
	export EXAMPLE_SEARCH_API_KEY='your-key'
	python -m agentic_rag serve
	```

	启动日志会显示每个 MCP Server 的连接结果。连接成功的工具会注册到工具中心，并在所有 Agent 模式中可用。

	> ⚠️ 不要把真实 API Key 提交到 Git。若密钥曾进入仓库历史，请立即撤销并轮换。

	### 语音与消息网关

	#### 语音 REST 接口

	```bash
	curl -N -X POST http://localhost:8007/api/v1/chat/voice \
	-F 'audio=@recording.wav' \
	-F 'sid=voice-demo' \
	-F 'tts=true'
	```

	响应为 SSE，事件类型：`transcript`、`text_delta`、工具事件、`audio`、`error`、`done`。

	支持的配置：
	- STT：`sensevoice`、`whisper`、`openai`
	- TTS：`qwen`、`kokoro`、`edge`、`openai`

	#### 消息网关

	支持企业微信、QQ Bot、钉钉。总开关 `GATEWAY__ENABLED=true`，各平台需单独配置凭据。

	> 生产使用前请完成平台签名校验、回调地址、权限和消息发送链路测试。

	### 功能状态

	\| 能力 \| 状态 \| 说明 \|
	\|------\|:----:\|------\|
	\| 非流式/流式聊天 \| ✅ \| REST、CLI；WebSocket 支持流式事件 \|
	\| `rag_search` \| ✅ \| Chat API 启动时自动注册 \|
	\| 文本与文件入库 \| ✅ \| REST 与 CLI 均有入口 \|
	\| 多模态上传 \| ✅ \| REST `/api/v1/rag/upload` \|
	\| `chat` / `research` 模式 \| ✅ \| 均可使用 RAG 与已连接的 MCP 工具 \|
	\| `rag` 模式 Agent 自主入库 \| ⚠️ \| 路由声明了 `rag_ingest`，但 Chat API 默认只注册 `rag_search` \|
	\| `media` 模式工具 \| ⚠️ \| 路由已定义，媒体工具未由 Chat API 默认注册 \|
	\| MCP \| ⚠️ \| 取决于本机命令、依赖、网络和环境变量 \|
	\| PDF/Office 解析 \| ⚠️ \| 需要 PaddleOCR-VL 服务、`pymupdf` 或 `docling` \|
	\| 语音对话 \| ⚠️ \| 需要可用的 STT/TTS 服务或本地模型 \|
	\| 消息平台网关 \| ⚠️ \| 企业微信、QQ Bot、钉钉需按平台配置与联调 \|

	---

	## AX8850 运行示例

	本节介绍在爱芯（AXERA）AX650N/AX8850 边缘设备上的两种部署方式：

	- 分离部署 — 仅模型推理服务运行在 NPU 设备上，通过 OpenAI 兼容接口对外提供；Agentic RAG 主机通过 HTTP 连接这些服务。
	- 全量部署（本节默认方式）— 完整的 Agentic RAG 服务也运行在 NPU 设备上，推理与应用同机完成，数据不出设备。

	### 1. 下载模型与运行组件

	可从以下官方资源选择适配 AX650N/AX8850 的模型和运行组件：

	- [AXERA-TECH Hugging Face 模型仓库](https://huggingface.co/AXERA-TECH)
	- [AXERA-TECH/ax-llm](https://github.com/AXERA-TECH/ax-llm)（LLM/VLM/Embedding 推理及 OpenAI 兼容服务）
	- [AX650 Community Hub](https://github.com/AXERA-TECH/AX650-Community-Hub)（SDK、部署文档和模型示例）

	本项目至少需要以下两类模型：

	\| 服务 \| 用途 \| 接口要求 \| 示例端口 \|
	\|------\|------\|----------\|---------:\|
	\| Chat LLM/VLM \| 对话、Agent 推理、图片理解 \| OpenAI 兼容 `/v1/chat/completions` \| `8009` \|
	\| Embedding \| 文本/图片/音视频向量化 \| OpenAI 兼容 `/v1/embeddings` \| `8010` \|

	可选模型服务：

	\| 服务 \| 用途 \| 接口要求 \| 示例端口 \|
	\|------\|------\|----------\|---------:\|
	\| [SenseVoice](https://huggingface.co/AXERA-TECH/SenseVoice_AgenticRAG) \| 语音识别 \| `/v1/audio/transcriptions` 或 `/asr` \| `8011` \|
	\| [Kokoro TTS](https://modelscope.cn/models/AXERA-TECH/kokoro.axera) \| 语音合成 \| `POST /tts`，返回 WAV \| `8012` \|
	\| PaddleOCR-VL \| PDF/图片 OCR \| OpenAI 兼容接口 \| `8013` \|

	### 2. 准备运行环境

	Agentic RAG 主机安装项目依赖。若启用语音、文档和媒体处理，建议安装完整可选依赖：

	```bash
	python -m venv .venv
	source .venv/bin/activate
	pip install -e ".[voice,documents,media]"

	# 压缩音频解码还需要系统提供 ffmpeg
	ffmpeg -version
	```

	如果只使用文本问答和 RAG，可直接执行：

	```bash
	pip install -e .
	```

	### 3. 启动模型服务

	以下命令在 AX8850 设备上执行。将模型目录替换为实际下载路径：

	```bash
	# LLM/VLM 模型
	axllm serve /path/to/llm-or-vlm-model --host 0.0.0.0 --port 8009

	# Embedding 模型
	axllm serve /path/to/embeddings-model --host 0.0.0.0 --port 8010

	# SenseVoice 模型
	python /path/to/SenseVoice/python/openai_server.py --port 8011

	# Kokoro 模型
	python /path/to/kokoro/kokoro_svr.py --port 8012
	```

	SenseVoice、Kokoro 和 PaddleOCR-VL 的启动命令以各自模型仓库为准。配置前应确认它们分别满足本项目使用的接口约定：

	- SenseVoice：优先支持 `POST /v1/audio/transcriptions`，也兼容 `POST /asr`
	- Kokoro：支持 `POST /tts`，接收 `text`、`language`、`voice`、`speed` 字段并返回音频字节
	- PaddleOCR-VL：提供 OpenAI 兼容的视觉模型接口

	### 4. 配置环境变量

	在项目根目录创建或修改 `.env`。以下示例假设所有模型服务都运行在 `192.168.1.100`：

	```bash
	# ============ LLM/VLM 服务 ============
	DEFAULT_PROVIDER=local
	LLM_PROVIDERS__LOCAL__API_BASE=http://192.168.1.100:8009/v1
	LLM_PROVIDERS__LOCAL__API_KEY=not-needed
	LLM_PROVIDERS__LOCAL__MODEL=your-chat-model
	LLM_PROVIDERS__LOCAL__VISION_MODEL=your-vision-model
	LLM_PROVIDERS__LOCAL__MAX_TOKENS=4096
	LLM_PROVIDERS__LOCAL__TEMPERATURE=0.7

	# ============ Embedding 服务 ============
	EMBEDDING__PROVIDER=local
	EMBEDDING__API_BASE=http://192.168.1.100:8010/v1
	EMBEDDING__API_KEY=not-needed
	EMBEDDING__MODEL=AXERA-TECH/jina-embeddings-v5-omni-nano-retrieval-AX650-P128-CTX2047
	EMBEDDING__MODEL_TYPE=multimodal
	EMBEDDING__DIM=768
	EMBEDDING__BATCH_SIZE=4

	# Milvus Lite 的向量维度必须与 Embedding 输出一致
	MILVUS__DIM=768

	# ============ 可选：SenseVoice STT ============
	VOICE__STT_PROVIDER=sensevoice
	VOICE__STT_MODEL=sensevoice
	VOICE__STT_API_BASE=http://192.168.1.100:8011
	VOICE__STT_LANGUAGE=auto
	VOICE__SAMPLE_RATE=16000

	# ============ 可选：Kokoro TTS ============
	VOICE__TTS_PROVIDER=kokoro
	VOICE__TTS_MODEL=kokoro
	VOICE__TTS_API_BASE=http://192.168.1.100:8012
	VOICE__TTS_LANGUAGE=zh
	VOICE__TTS_VOICE=zf_xiaoyi
	VOICE__TTS_SPEED=1.0
	VOICE__TTS_RESPONSE_FORMAT=wav

	# ============ 可选：PaddleOCR-VL ============
	OCR__ENABLED=true
	OCR__API_BASE=http://192.168.1.100:8013/v1
	OCR__MODEL=PaddlePaddle/PaddleOCR-VL
	OCR__API_KEY=not-needed
	OCR__MAX_PAGES=50

	# ============ Agentic RAG Web 服务 ============
	API__HOST=0.0.0.0
	API__PORT=8007
	```

	注意事项：

	1. `LLM_PROVIDERS__LOCAL__MODEL` 必须与模型服务实际暴露的模型名一致。这里使用已注册的 `local` Provider 连接 AX8850 上的 OpenAI 兼容服务，无需新增 Provider 类型。
	2. 纯文本模型不支持图片输入时，将 `VISION_MODEL` 配置为单独的 VLM；如果服务中没有视觉模型，请留空并避免使用图片理解功能。
	3. `EMBEDDING__DIM` 和 `MILVUS__DIM` 必须一致。更换向量维度后，需要备份并删除旧的 `workspace/milvus_lite.db`，再重新入库。
	4. 使用多模态 Embedding 时建议设置 `EMBEDDING__MODEL_TYPE=multimodal`。
	5. 如果 AX8850 上只启动了核心的 LLM 和 Embedding 服务，可删除或注释 STT、TTS、OCR 配置。

	### 5. 启动项目

	```bash
	# 首次运行或前端发生变化时构建 Web UI
	cd frontend && npm install && npm run build && cd ..

	# 启动后端及 Web UI
	python -m agentic_rag serve --host 0.0.0.0 --port 8007
	```

	---