LightRAG API服务与Web界面开发

最新推荐文章于 2025-09-11 11:29:10 发布
原创 最新推荐文章于 2025-09-11 11:29:10 发布 · 998 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

LightRAG API服务与Web界面开发

【免费下载链接】LightRAG "LightRAG: Simple and Fast Retrieval-Augmented Generation" 【免费下载链接】LightRAG 项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG

LightRAG提供了一套完整的RESTful API接口，支持文档管理、知识图谱查询、智能问答等多种功能。这些API基于FastAPI框架构建，提供了高性能的异步处理和丰富的参数配置选项。Web界面则提供了强大的文档索引管理和知识图谱可视化功能，让用户能够直观地管理和探索构建的知识网络。

RESTful API接口设计与使用

LightRAG提供了一套完整的RESTful API接口，支持文档管理、知识图谱查询、智能问答等多种功能。这些API基于FastAPI框架构建，提供了高性能的异步处理和丰富的参数配置选项。

API基础架构

LightRAG的API架构采用模块化设计，主要包含以下几个核心路由模块：

mermaid

核心API接口详解

1. 查询接口（Query API）

查询接口是LightRAG最核心的功能，支持多种检索模式和丰富的参数配置。

基础查询端点：

POST /api/query
Content-Type: application/json

{
  "query": "LightRAG的主要特性是什么？",
  "mode": "mix",
  "top_k": 50,
  "response_type": "Bullet Points"
}

流式查询端点：

POST /api/query/stream
Content-Type: application/json

{
  "query": "请详细解释LightRAG的工作原理",
  "mode": "hybrid"
}
2. 查询参数详解

LightRAG的查询请求支持丰富的参数配置，以下是主要的参数说明：

参数名类型默认值描述
querystring必需查询文本内容
modeenum"mix"检索模式：local/global/hybrid/naive/mix/bypass
top_kinteger50检索的top-k数量
chunk_top_kinteger20文本片段检索数量
response_typestringnull响应格式类型
enable_rerankbooleantrue是否启用重排序

检索模式说明：

mermaid

3. 文档管理接口

文档管理接口支持文档的上传、查询、删除等操作：

上传文档：

POST /api/documents/upload
Content-Type: multipart/form-data

文件字段：file

批量插入文本：

POST /api/documents/insert-texts
Content-Type: application/json

{
  "texts": ["文本内容1", "文本内容2"],
  "file_sources": ["source1", "source2"]
}

查询文档状态：

GET /api/documents
4. 知识图谱接口

知识图谱接口提供对实体和关系的查询与管理：

获取图谱标签：

GET /api/graph/labels

查询知识图谱：

GET /api/graph/knowledge-graph?label=technology&max_depth=3&max_nodes=100

检查实体存在：

GET /api/graph/check-entity?name=人工智能

API使用示例

Python客户端示例
import requests
import json

class LightRAGClient:
    def __init__(self, base_url="http://localhost:9621", api_key=None):
        self.base_url = base_url
        self.headers = {"Content-Type": "application/json"}
        if api_key:
            self.headers["Authorization"] = f"Bearer {api_key}"
    
    def query(self, question, mode="mix", top_k=50):
        payload = {
            "query": question,
            "mode": mode,
            "top_k": top_k
        }
        response = requests.post(
            f"{self.base_url}/api/query",
            headers=self.headers,
            json=payload
        )
        return response.json()
    
    def stream_query(self, question, mode="hybrid"):
        payload = {
            "query": question,
            "mode": mode
        }
        response = requests.post(
            f"{self.base_url}/api/query/stream",
            headers=self.headers,
            json=payload,
            stream=True
        )
        
        for line in response.iter_lines():
            if line:
                data = json.loads(line)
                yield data.get("response", "")

# 使用示例
client = LightRAGClient()

# 普通查询
result = client.query("LightRAG支持哪些存储后端？")
print(result["response"])

# 流式查询
for chunk in client.stream_query("请详细说明LightRAG的架构设计"):
    print(chunk, end="", flush=True)
cURL命令示例

基础查询：

curl -X POST "http://localhost:9621/api/query" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "LightRAG的主要特性",
    "mode": "mix",
    "top_k": 30
  }'

流式查询：

curl -X POST "http://localhost:9621/api/query/stream" \
  -H "Content-Type: application/json" \
  -d '{"query": "解释RAG技术"}' \
  --no-buffer

高级功能配置

1. 对话历史支持

LightRAG支持维护对话上下文，提供更连贯的问答体验：

conversation_history = [
    {"role": "user", "content": "什么是检索增强生成？"},
    {"role": "assistant", "content": "检索增强生成是一种结合信息检索和文本生成的技术..."}
]

payload = {
    "query": "它有什么优势？",
    "conversation_history": conversation_history,
    "history_turns": 2
}
2. 令牌预算控制

支持精细化的令牌分配控制：

payload = {
    "query": "复杂技术问题",
    "max_entity_tokens": 1000,
    "max_relation_tokens": 1500,
    "max_total_tokens": 4000
}
3. 响应格式定制

支持指定响应格式类型：

payload = {
    "query": "列出主要功能",
    "response_type": "Bullet Points"
}

错误处理与状态码

LightRAG API使用标准的HTTP状态码：

状态码含义处理建议
200成功正常处理响应
400请求错误检查参数格式
401未授权提供有效的API密钥
500服务器错误查看服务器日志

性能优化建议

  1. 使用流式接口：对于长文本生成，使用流式接口可以显著改善用户体验
  2. 合理设置top_k：根据查询复杂度调整top_k参数，平衡精度和性能
  3. 启用缓存：重复查询会自动使用缓存结果，提高响应速度
  4. 批量操作：文档上传和文本插入支持批量操作，减少API调用次数

LightRAG的RESTful API设计注重开发者的使用体验，提供了丰富的功能和灵活的配置选项，使得集成和定制化变得简单高效。通过合理的参数配置和最佳实践，可以获得最优的检索和生成效果。

Web UI文档索引与知识图谱可视化

LightRAG的Web界面提供了强大的文档索引管理和知识图谱可视化功能，让用户能够直观地管理和探索构建的知识网络。这一功能集成了先进的图数据库技术和现代化的前端可视化框架，为用户提供了完整的文档生命周期管理和知识图谱交互体验。

文档索引管理

LightRAG Web UI的文档管理界面采用分页表格设计，支持多种状态筛选和排序功能，让用户能够高效地管理大量文档。

文档状态管理

文档在索引过程中会经历不同的状态，Web UI提供了清晰的状态标识和筛选功能：

状态描述颜色标识
pending文档已上传但尚未开始处理灰色
processing文档正在处理中蓝色
processed文档已成功处理并索引绿色
failed文档处理失败红色
// 文档状态类型定义
export type DocStatus = 'pending' | 'processing' | 'processed' | 'failed'

// 文档状态响应结构
export type DocStatusResponse = {
  id: string
  content_summary: string
  content_length: number
  status: DocStatus
  created_at: string
  updated_at: string
  track_id?: string
  chunks_count?: number
  error_msg?: string
  metadata?: Record<string, any>
  file_path: string
}
批量操作功能

Web UI支持多种文档批量操作：

  • 文档上传：支持拖拽上传和文件选择器，可批量上传多个文档
  • 状态筛选：按处理状态筛选文档，快速定位特定状态的文档
  • 批量删除：选择多个文档进行批量删除操作
  • 重新扫描：重新扫描输入目录，发现并索引新文档
// 文档扫描API
export const scanNewDocuments = async (): Promise<ScanResponse> => {
  const response = await axiosInstance.post('/documents/scan')
  return response.data
}

// 批量删除API  
export const deleteDocuments = async (
  docIds: string[], 
  deleteFile: boolean = false
): Promise<DeleteDocResponse> => {
  const response = await axiosInstance.post('/documents/delete', {
    doc_ids: docIds,
    delete_file: deleteFile
  })
  return response.data
}

知识图谱可视化

LightRAG的知识图谱可视化基于Sigma.js图可视化库构建，提供了丰富的交互功能和可视化效果。

图谱数据模型

知识图谱由节点（实体）和边（关系）组成，每个元素都包含丰富的属性信息：

// 图谱节点类型定义
export type LightragNodeType = {
  id: string
  labels: string[]
  properties: Record<string, any>
}

// 图谱边类型定义  
export type LightragEdgeType = {
  id: string
  source: string
  target: string
  type: string
  properties: Record<string, any>
}

// 完整图谱数据结构
export type LightragGraphType = {
  nodes: LightragNodeType[]
  edges: LightragEdgeType[]
}
可视化交互功能

Web UI提供了全面的图谱交互功能：

mermaid

图谱查询与探索

Web UI支持多种图谱查询方式：

  1. 标签筛选查询：按实体标签过滤图谱节点
  2. 深度探索：设置探索深度，发现关联实体
  3. 节点数量控制：限制返回节点数量，优化性能
// 图谱查询API
export const queryGraphs = async (
  label: string,
  maxDepth: number,
  maxNodes: number
): Promise<LightragGraphType> => {
  const response = await axiosInstance.get(
    `/graphs?label=${encodeURIComponent(label)}&max_depth=${maxDepth}&max_nodes=${maxNodes}`
  )
  return response.data
}

// 获取图谱标签列表
export const getGraphLabels = async (): Promise<string[]> => {
  const response = await axiosInstance.get('/graph/label/list')
  return response.data
}

实时处理状态监控

Web UI提供了实时的文档处理状态监控，让用户能够清晰了解索引进度：

// 处理状态响应结构
export type PipelineStatusResponse = {
  autoscanned: boolean
  busy: boolean
  job_name: string
  job_start?: string
  docs: number
  batchs: number
  cur_batch: number
  request_pending: boolean
  latest_message: string
  history_messages?: string[]
  update_status?: Record<string, any>
}

// 文档扫描进度监控
export type LightragDocumentsScanProgress = {
  is_scanning: boolean
  current_file: string
  indexed_count: number
  total_files: number
  progress: number
}

可视化配置选项

Web UI提供了丰富的可视化配置选项，用户可以根据需要自定义图谱显示效果：

配置项描述默认值
显示属性面板是否显示节点/边的属性详情面板开启
显示节点搜索栏是否显示节点搜索功能开启
启用节点拖拽是否允许手动调整节点位置开启
显示图例是否显示图谱图例说明开启
标签显示阈值节点标签显示的最小尺寸12px

响应式设计

Web UI采用响应式设计，适配不同屏幕尺寸：

  • 桌面端：完整功能布局，侧边栏+主内容区
  • 平板端：自适应布局，优化触控交互
  • 移动端：简化界面，核心功能优先

性能优化

针对大规模图谱数据的性能优化措施：

  1. 分页加载：文档列表分页显示，避免一次性加载过多数据
  2. 节点数量限制：图谱查询支持最大节点数限制
  3. WebGL加速：使用Sigma.js的WebGL渲染引擎
  4. 异步加载：所有数据操作均采用异步方式

LightRAG的Web UI文档索引与知识图谱可视化功能为用户提供了直观、高效的知识管理界面，使得复杂的RAG系统变得易于操作和理解。通过丰富的交互功能和实时的状态反馈，用户可以轻松地构建、管理和探索自己的知识库。

身份验证与权限管理系统

LightRAG提供了一个灵活且强大的身份验证与权限管理系统，支持多种认证方式，包括API密钥认证、JWT令牌认证以及访客模式。该系统设计旨在为不同部署场景提供适当的安全级别，从本地开发环境的无认证模式到生产环境的多用户认证系统。

认证架构概述

LightRAG的认证系统采用分层架构，支持以下认证机制：

mermaid

认证配置选项

LightRAG支持通过环境变量配置认证系统，主要配置参数如下：

环境变量默认值描述
AUTH_ACCOUNTS空用户账户列表，格式：username1:password1,username2:password2
TOKEN_SECRETlightrag-jwt-default-secretJWT令牌签名密钥
TOKEN_EXPIRE_HOURS48普通用户令牌过期时间（小时）
GUEST_TOKEN_EXPIRE_HOURS24访客令牌过期时间（小时）
JWT_ALGORITHMHS256JWT签名算法
LIGHTRAG_API_KEY空API密钥认证
WHITELIST_PATHS/health,/api/*免认证路径白名单

JWT令牌认证系统

LightRAG使用基于JWT（JSON Web Tokens）的认证系统，支持用户角色管理和令牌过期策略。

令牌生成与验证
# JWT令牌载荷结构示例
token_payload = {
    "sub": "username",        # 用户名
    "exp": "2025-08-25T16:40:04",  # 过期时间
    "role": "user",           # 用户角色（user/guest）
    "metadata": {             # 附加元数据
        "auth_mode": "enabled"
    }
}
令牌管理API

登录端点 - POST /login

# 请求示例
curl -X POST "http://localhost:9621/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123"

响应示例（认证已启用）：

{
  "access_token": "eyJhbGciOiJIUzI

【免费下载链接】LightRAG "LightRAG: Simple and Fast Retrieval-Augmented Generation" 【免费下载链接】LightRAG 项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值