diff --git a/env.ollama-binding-options.example b/env.ollama-binding-options.example deleted file mode 100644 index f3c8181e..00000000 --- a/env.ollama-binding-options.example +++ /dev/null @@ -1,195 +0,0 @@ -################################################################################ -# Autogenerated .env entries list for LightRAG binding options -# -# To generate run: -# $ python -m lightrag.llm.binding_options -################################################################################ -# ollama_embedding -- Context window size (number of tokens) -# OLLAMA_EMBEDDING_NUM_CTX=4096 - -# ollama_embedding -- Maximum number of tokens to predict -# OLLAMA_EMBEDDING_NUM_PREDICT=128 - -# ollama_embedding -- Number of tokens to keep from the initial prompt -# OLLAMA_EMBEDDING_NUM_KEEP=0 - -# ollama_embedding -- Random seed for generation (-1 for random) -# OLLAMA_EMBEDDING_SEED=-1 - -# ollama_embedding -- Controls randomness (0.0-2.0, higher = more creative) -# OLLAMA_EMBEDDING_TEMPERATURE=0.8 - -# ollama_embedding -- Top-k sampling parameter (0 = disabled) -# OLLAMA_EMBEDDING_TOP_K=40 - -# ollama_embedding -- Top-p (nucleus) sampling parameter (0.0-1.0) -# OLLAMA_EMBEDDING_TOP_P=0.9 - -# ollama_embedding -- Tail free sampling parameter (1.0 = disabled) -# OLLAMA_EMBEDDING_TFS_Z=1.0 - -# ollama_embedding -- Typical probability mass (1.0 = disabled) -# OLLAMA_EMBEDDING_TYPICAL_P=1.0 - -# ollama_embedding -- Minimum probability threshold (0.0 = disabled) -# OLLAMA_EMBEDDING_MIN_P=0.0 - -# ollama_embedding -- Number of tokens to consider for repetition penalty -# OLLAMA_EMBEDDING_REPEAT_LAST_N=64 - -# ollama_embedding -- Penalty for repetition (1.0 = no penalty) -# OLLAMA_EMBEDDING_REPEAT_PENALTY=1.1 - -# ollama_embedding -- Penalty for token presence (-2.0 to 2.0) -# OLLAMA_EMBEDDING_PRESENCE_PENALTY=0.0 - -# ollama_embedding -- Penalty for token frequency (-2.0 to 2.0) -# OLLAMA_EMBEDDING_FREQUENCY_PENALTY=0.0 - -# ollama_embedding -- Mirostat sampling algorithm (0=disabled, 1=Mirostat 1.0, 2=Mirostat 2.0) -# OLLAMA_EMBEDDING_MIROSTAT=0 - -# ollama_embedding -- Mirostat target entropy -# OLLAMA_EMBEDDING_MIROSTAT_TAU=5.0 - -# ollama_embedding -- Mirostat learning rate -# OLLAMA_EMBEDDING_MIROSTAT_ETA=0.1 - -# ollama_embedding -- Enable NUMA optimization -# OLLAMA_EMBEDDING_NUMA=False - -# ollama_embedding -- Batch size for processing -# OLLAMA_EMBEDDING_NUM_BATCH=512 - -# ollama_embedding -- Number of GPUs to use (-1 for auto) -# OLLAMA_EMBEDDING_NUM_GPU=-1 - -# ollama_embedding -- Main GPU index -# OLLAMA_EMBEDDING_MAIN_GPU=0 - -# ollama_embedding -- Optimize for low VRAM -# OLLAMA_EMBEDDING_LOW_VRAM=False - -# ollama_embedding -- Number of CPU threads (0 for auto) -# OLLAMA_EMBEDDING_NUM_THREAD=0 - -# ollama_embedding -- Use half-precision for key/value cache -# OLLAMA_EMBEDDING_F16_KV=True - -# ollama_embedding -- Return logits for all tokens -# OLLAMA_EMBEDDING_LOGITS_ALL=False - -# ollama_embedding -- Only load vocabulary -# OLLAMA_EMBEDDING_VOCAB_ONLY=False - -# ollama_embedding -- Use memory mapping for model files -# OLLAMA_EMBEDDING_USE_MMAP=True - -# ollama_embedding -- Lock model in memory -# OLLAMA_EMBEDDING_USE_MLOCK=False - -# ollama_embedding -- Only use for embeddings -# OLLAMA_EMBEDDING_EMBEDDING_ONLY=False - -# ollama_embedding -- Penalize newline tokens -# OLLAMA_EMBEDDING_PENALIZE_NEWLINE=True - -# ollama_embedding -- Stop sequences (comma-separated string) -# OLLAMA_EMBEDDING_STOP= - -# ollama_llm -- Context window size (number of tokens) -# OLLAMA_LLM_NUM_CTX=4096 - -# ollama_llm -- Maximum number of tokens to predict -# OLLAMA_LLM_NUM_PREDICT=128 - -# ollama_llm -- Number of tokens to keep from the initial prompt -# OLLAMA_LLM_NUM_KEEP=0 - -# ollama_llm -- Random seed for generation (-1 for random) -# OLLAMA_LLM_SEED=-1 - -# ollama_llm -- Controls randomness (0.0-2.0, higher = more creative) -# OLLAMA_LLM_TEMPERATURE=0.8 - -# ollama_llm -- Top-k sampling parameter (0 = disabled) -# OLLAMA_LLM_TOP_K=40 - -# ollama_llm -- Top-p (nucleus) sampling parameter (0.0-1.0) -# OLLAMA_LLM_TOP_P=0.9 - -# ollama_llm -- Tail free sampling parameter (1.0 = disabled) -# OLLAMA_LLM_TFS_Z=1.0 - -# ollama_llm -- Typical probability mass (1.0 = disabled) -# OLLAMA_LLM_TYPICAL_P=1.0 - -# ollama_llm -- Minimum probability threshold (0.0 = disabled) -# OLLAMA_LLM_MIN_P=0.0 - -# ollama_llm -- Number of tokens to consider for repetition penalty -# OLLAMA_LLM_REPEAT_LAST_N=64 - -# ollama_llm -- Penalty for repetition (1.0 = no penalty) -# OLLAMA_LLM_REPEAT_PENALTY=1.1 - -# ollama_llm -- Penalty for token presence (-2.0 to 2.0) -# OLLAMA_LLM_PRESENCE_PENALTY=0.0 - -# ollama_llm -- Penalty for token frequency (-2.0 to 2.0) -# OLLAMA_LLM_FREQUENCY_PENALTY=0.0 - -# ollama_llm -- Mirostat sampling algorithm (0=disabled, 1=Mirostat 1.0, 2=Mirostat 2.0) -# OLLAMA_LLM_MIROSTAT=0 - -# ollama_llm -- Mirostat target entropy -# OLLAMA_LLM_MIROSTAT_TAU=5.0 - -# ollama_llm -- Mirostat learning rate -# OLLAMA_LLM_MIROSTAT_ETA=0.1 - -# ollama_llm -- Enable NUMA optimization -# OLLAMA_LLM_NUMA=False - -# ollama_llm -- Batch size for processing -# OLLAMA_LLM_NUM_BATCH=512 - -# ollama_llm -- Number of GPUs to use (-1 for auto) -# OLLAMA_LLM_NUM_GPU=-1 - -# ollama_llm -- Main GPU index -# OLLAMA_LLM_MAIN_GPU=0 - -# ollama_llm -- Optimize for low VRAM -# OLLAMA_LLM_LOW_VRAM=False - -# ollama_llm -- Number of CPU threads (0 for auto) -# OLLAMA_LLM_NUM_THREAD=0 - -# ollama_llm -- Use half-precision for key/value cache -# OLLAMA_LLM_F16_KV=True - -# ollama_llm -- Return logits for all tokens -# OLLAMA_LLM_LOGITS_ALL=False - -# ollama_llm -- Only load vocabulary -# OLLAMA_LLM_VOCAB_ONLY=False - -# ollama_llm -- Use memory mapping for model files -# OLLAMA_LLM_USE_MMAP=True - -# ollama_llm -- Lock model in memory -# OLLAMA_LLM_USE_MLOCK=False - -# ollama_llm -- Only use for embeddings -# OLLAMA_LLM_EMBEDDING_ONLY=False - -# ollama_llm -- Penalize newline tokens -# OLLAMA_LLM_PENALIZE_NEWLINE=True - -# ollama_llm -- Stop sequences (comma-separated string) -# OLLAMA_LLM_STOP= - -# -# End of .env entries for LightRAG binding options -################################################################################ diff --git a/paging.md b/paging.md deleted file mode 100644 index 716b7297..00000000 --- a/paging.md +++ /dev/null @@ -1,251 +0,0 @@ -# 文档列表页面分页显示功能改造方案 - -## 一、改造目标 - -### 问题现状 -- 当前文档页面一次性加载所有文档,导致大量文档时界面加载慢 -- 前端内存占用过大,用户操作体验差 -- 状态过滤和排序都在前端进行,效率低下 - -### 改造目标 -- 实现后端分页查询,减少单次数据传输量 -- 添加分页控制组件,支持翻页和跳转功能 -- 允许用户设置每页显示行数(10-200条) -- 保持现有状态过滤和排序功能不变 -- 提升大数据量场景下的性能表现 - -## 二、总体架构设计 - -### 设计原则 -1. **统一分页接口**:后端提供统一的分页API,支持状态过滤和排序 -2. **智能刷新策略**:根据处理状态选择合适的刷新频率和范围 -3. **即时用户反馈**:状态切换、分页操作提供立即响应 -4. **向后兼容**:保持现有功能完整性,不影响现有操作流程 -5. **性能优化**:减少内存占用,优化网络请求 - -### 技术方案 -- **后端**:在现有存储层基础上添加分页查询接口 -- **前端**:改造DocumentManager组件,添加分页控制 -- **数据流**:统一分页查询 + 独立状态计数查询 - -## 三、后端改造步骤 - -### 步骤1:存储层接口扩展 - -**改动文件**:`lightrag/kg/base.py` - -**关键思路**: -- 在BaseDocStatusStorage抽象类中添加分页查询方法 -- 设计统一的分页接口,支持状态过滤、排序、分页参数 -- 返回文档列表和总数量的元组 - -**接口设计要点**: -``` -get_docs_paginated(status_filter, page, page_size, sort_field, sort_direction) -> (documents, total_count) -count_by_status(status) -> int -get_all_status_counts() -> Dict[str, int] -``` - -### 步骤2:各存储后端实现 - -**改动文件**: -- `lightrag/kg/postgres_impl.py` -- `lightrag/kg/mongo_impl.py` -- `lightrag/kg/redis_impl.py` -- `lightrag/kg/json_doc_status_impl.py` - -**PostgreSQL实现要点**: -- 使用LIMIT和OFFSET实现分页 -- 构建动态WHERE条件支持状态过滤 -- 使用COUNT查询获取总数量 -- 添加合适的数据库索引优化查询性能 - -**MongoDB实现要点**: -- 使用skip()和limit()实现分页 -- 使用聚合管道进行状态统计 -- 优化查询条件和索引 - -**Redis 与 Json实现要点:** - -* 考虑先用简单的方式实现,即把所有文件清单读到内存中后进行过滤和排序 - -**关键考虑**: - -- 确保各存储后端的分页逻辑一致性 -- 处理边界情况(空结果、超出页码范围等) -- 优化查询性能,避免全表扫描 - -### 步骤3:API路由层改造 - -**改动文件**:`lightrag/api/routers/document_routes.py` - -**新增接口**: -1. `POST /documents/paginated` - 分页查询文档 -2. `GET /documents/status_counts` - 获取状态计数 - -**数据模型设计**: -- DocumentsRequest:分页请求参数 -- PaginatedDocsResponse:分页响应数据 -- PaginationInfo:分页元信息 - -**关键逻辑**: -- 参数验证(页码范围、页面大小限制) -- 并行查询分页数据和状态计数 -- 错误处理和异常响应 - -### 步骤4:数据库优化 - -**索引策略**: -- 为workspace + status + updated_at创建复合索引 -- 为workspace + status + created_at创建复合索引 -- 为workspace + updated_at创建索引 -- 为workspace + created_at创建索引 - -**性能考虑**: -- 避免深度分页的性能问题 -- 考虑添加缓存层优化状态计数查询 -- 监控查询性能,必要时调整索引策略 - -## 四、前端改造步骤 - -### 步骤1:API客户端扩展 - -**改动文件**:`lightrag_webui/src/api/lightrag.ts` - -**新增函数**: -- `getDocumentsPaginated()` - 分页查询文档 -- `getDocumentStatusCounts()` - 获取状态计数 - -**类型定义**: -- 定义分页请求和响应的TypeScript类型 -- 确保类型安全和代码提示 - -### 步骤2:分页控制组件开发 - -**新增文件**:`lightrag_webui/src/components/ui/PaginationControls.tsx` - -**组件功能**: -- 支持紧凑模式和完整模式 -- 页码输入和跳转功能 -- 每页显示数量选择(10-200) -- 总数信息显示 -- 禁用状态处理 - -**设计要点**: -- 响应式设计,适配不同屏幕尺寸 -- 防抖处理,避免频繁请求 -- 错误处理和状态回滚 -- 组件摆放位置:目前状态按钮上方,与scan按钮同一层,居中摆放 - -### 步骤3:状态过滤按钮优化 - -**改动文件**:现有状态过滤相关组件 - -**优化要点**: - -- 添加加载状态指示 -- 数据不足时的智能提示 -- 定期刷新数据,状态切换时如果最先的状态数据距离上次刷新数据超过5秒应即时刷新数据 -- 防止重复点击和并发请求 - -### 步骤4:主组件DocumentManager改造 - -**改动文件**:`lightrag_webui/src/features/DocumentManager.tsx` - -**核心改动**: - -**状态管理重构**: -- 将docs状态改为currentPageDocs(仅存储当前页数据) -- 添加pagination状态管理分页信息 -- 添加statusCounts状态独立管理状态计数 -- 添加加载状态管理(isStatusChanging, isRefreshing) - -**数据获取策略**: -- 实现智能刷新:活跃期完整刷新,稳定期轻量刷新 -- 状态切换时立即刷新数据 -- 分页操作时立即更新数据 -- 定期刷新与手动操作协调 - -**布局调整**: -- 将分页控制组件放置在顶部操作栏中间位置 -- 保持状态过滤按钮在表格上方 -- 确保响应式布局适配 - -**事件处理优化**: -- 状态切换时,如果当前页码数据不足,则重置到第一页 -- 页面大小变更时智能计算新页码 -- 错误时状态回滚机制 - -## 五、用户体验优化 - -### 即时反馈机制 -- 状态切换时显示加载动画 -- 分页操作时提供视觉反馈 -- 数据不足时智能提示用户 - -### 错误处理策略 -- 网络错误时自动重试 -- 操作失败时状态回滚 -- 友好的错误提示信息 - -### 性能优化措施 -- 防抖处理频繁操作 -- 智能刷新策略减少不必要请求 -- 组件卸载时清理定时器和请求 - -## 六、兼容性保障 - -### 向后兼容 -- 保留原有的/documents接口作为备用 -- 现有功能(排序、过滤、选择)保持不变 -- 渐进式升级,支持配置开关 - -### 数据一致性 -- 确保分页数据与状态计数同步 -- 处理并发更新的数据一致性问题 -- 定期刷新保持数据最新 - -## 七、测试策略 - -### 功能测试 -- 各种分页场景测试 -- 状态过滤组合测试 -- 排序功能验证 -- 边界条件测试 - -### 性能测试 -- 大数据量场景测试 -- 并发访问压力测试 -- 内存使用情况监控 -- 响应时间测试 - -### 兼容性测试 -- 不同存储后端测试 -- 不同浏览器兼容性 -- 移动端响应式测试 - -## 八、关键实现细节 - -### 后端分页查询设计 -- **统一接口**:所有存储后端实现相同的分页接口签名 -- **参数验证**:严格验证页码、页面大小、排序参数的合法性 -- **性能优化**:使用数据库原生分页功能,避免应用层分页 -- **错误处理**:统一的错误响应格式和异常处理机制 - -### 前端状态管理策略 -- **数据分离**:当前页数据与状态计数分别管理 -- **智能刷新**:根据文档处理状态选择刷新策略 -- **状态同步**:确保UI状态与后端数据保持一致 -- **错误恢复**:操作失败时自动回滚到之前状态 - -### 分页控制组件设计 -- **紧凑布局**:适配顶部操作栏的空间限制 -- **响应式设计**:在不同屏幕尺寸下自适应布局 -- **交互优化**:防抖处理、加载状态、禁用状态管理 -- **可访问性**:支持键盘导航和屏幕阅读器 - -### 数据库索引优化 -- **复合索引**:workspace + status + sort_field的组合索引 -- **覆盖索引**:尽可能使用覆盖索引减少回表查询 -- **索引监控**:定期监控索引使用情况和查询性能 -- **渐进优化**:根据实际使用情况调整索引策略