优化、性能与内存占用

本指南汇总 OPL 数据空间的性能优化思路。最合适的配置取决于你的部署目标，大致可以分成三类：

1. 弱硬件上的极致隐私：例如 Raspberry Pi。目标是全部本地运行、尽量省资源，代价是要关闭重功能并使用轻量模型。
2. 单用户的最佳体验：例如个人桌面环境。目标是速度和质量都尽量好，通常应把 Embedding、Task Model 等交给外部 API。
3. 多用户大规模部署：例如企业或生产环境。目标是稳定和并发，需要 PostgreSQL、独立 Vector DB、缓存和更大的线程池。

---

性能调优

1. 为后台任务单独指定轻量模型

OPL 数据空间会自动做标题生成、自动补全、打标签等后台任务。如果它们与主聊天模型共用同一套重型模型，会明显拖慢响应。

建议：

• 给后台任务使用 快速、小型、低成本、非推理类模型
• 避免使用 o1、r1、Claude 这类慢且贵的推理模型

配置位置：

• Task Model (External)：与外部模型聊天时使用
• Task Model (Local)：与本地模型聊天时使用

常见选择：

• 外部模型：gpt-5-nano、gemini-2.5-flash-lite
• 本地模型：qwen3:1b、gemma3:1b、llama3.2:3b

2. 缓存与延迟优化

模型缓存

对于 OpenRouter 这类模型非常多的 provider，缓存模型列表非常重要，否则管理页初次加载可能要十几秒。

ENABLE_BASE_MODELS_CACHE=True
MODELS_CACHE_TTL=300

搜索查询缓存

在同一个聊天轮次里复用 Web Search / RAG 生成的查询词，减少重复调用：

ENABLE_QUERIES_CACHE=True

KV Cache 优化（RAG）

把 RAG 上下文注入到 system message 中，而不是 user message：

RAG_SYSTEM_CONTEXT=True

这样更容易命中 KV prefix caching 或 prompt caching，对大文档追问的性能提升非常明显。

---

数据库优化

PostgreSQL 是规模化部署的前提

多用户或高并发场景下，必须使用 PostgreSQL。默认的 SQLite 不适合高并发写入，很容易出现锁冲突。

DATABASE_URL=postgres://user:password@localhost:5432/webui

聊天保存策略

不要在生产环境启用逐 token 实时保存：

ENABLE_REALTIME_CHAT_SAVE=False

它会显著增加数据库写压，导致连接池耗尽和整体性能恶化。

数据库 Session 共享

从 v0.7.1 起，可以通过共享数据库 session 减少高并发下的开销：

DATABASE_ENABLE_SESSION_SHARING=True

但要注意：

• SQLite：保持关闭
• 资源足够的 PostgreSQL：可考虑开启

低配硬件上如果页面变慢或请求超时，优先确认它没有被错误开启。

连接池大小

PostgreSQL 高并发部署时，如遇到 QueuePool limit reached，可以调大：

DATABASE_POOL_SIZE=15
DATABASE_POOL_MAX_OVERFLOW=20

总连接数不要逼近数据库本身的 max_connections。

---

Vector DB 与文档处理

Vector DB 选择

• ChromaDB 默认模式：不适合多 worker / 多副本。其本地 PersistentClient 依赖 SQLite，进程间并发写入容易崩。
• 更适合生产的选择：
  • Milvus
  • Qdrant
  • PGVector
  • ChromaDB HTTP 模式

如果使用 Milvus 或 Qdrant，多租户模式也值得开启。

内容提取引擎

默认内容提取器依赖的一些 Python 库在长期 ingest 文档时可能出现 内存泄漏。如果部署中经常上传文档，建议尽早切换到外部提取引擎：

• Apache Tika
• Docling
• PaddleOCR-vl
• External Loader

这样可以把最耗内存的解析过程挪出 OPL 数据空间主进程。

Embedding 引擎

Embedding 引擎

默认的 SentenceTransformers 会把模型加载到 OPL 数据空间进程里，规模化时会带来额外内存压力，并且每个 worker 都会各自加载一份。

生产环境建议改为外部 Embedding：

RAG_EMBEDDING_ENGINE=openai

或者使用 Ollama 等外部自托管 Embedding 服务。

文档分块

建议启用 Markdown Header Splitting，并设置最小分块目标，避免大量过小 chunk：

CHUNK_MIN_SIZE_TARGET=1000

这有助于减少向量数量，并提升检索效果。

---

基础设施扩展

基础设施扩展

对于企业级部署，请参考 Scaling OPL 数据空间。几个关键点：

• 多副本 / 多 worker 场景下，Redis 是必需的
• Ingress / 负载均衡层最好支持 Session Affinity
• 反向代理要缓存静态资源
• 如果使用 Nginx，务必关闭 proxy_buffering，否则会导致流式输出变慢甚至 markdown 乱码

---

高并发与网络优化

批量发送流式 token

默认情况下， OPL 数据空间会按 token 逐个推送流式输出。高并发时可以适度提高批量大小：

CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE=7

通常设置成 5-10 比较合适。

线程池大小

线程池过小会直接导致请求卡死：

THREAD_POOL_SIZE=2000

文档明确建议 不要随意调低。

AIOHTTP 超时

长时间推理任务需要更高的超时设置：

AIOHTTP_CLIENT_TIMEOUT=1800
AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=15

SQLite 与存储磁盘 IO 延迟

如果你仍在使用 SQLite，底层磁盘或网络存储延迟会直接拖慢管理页、聊天保存和文档处理。生产环境下这通常意味着应该尽快迁移到 PostgreSQL，并避免把 SQLite 放在高延迟卷上。