二次开发复杂度评估（SDCI）
标准化量表评估二开复杂度，给出 onyx/LightRAG/SurfSense/RAG-Anything 等项目的客观打分与选型建议
什么是 SDCI？
SDCI（Secondary Development Complexity Index）用于量化一个开源项目在企业落地过程中的二次开发与维护复杂度，帮助团队在选型前做成本预估与风险识别。
二次开发复杂度评估（SDCI）
评估维度与权重
| 维度 | 权重 | 评估要点 |
|---|---|---|
| 架构与模块边界 | 20% | 目录清晰、边界清楚、低耦合、清晰的分层 |
| 扩展面/插件化 | 25% | 检索/存储/Embedding/Agent 可插拔、Hook/接口稳定 |
| 配置与参数管理 | 10% | 配置分层（env/tenant/envoy）、动态热更新、A/B 支持 |
| 依赖与构建链路 | 10% | 依赖数量、可缓存构建、CI/CD、镜像体积 |
| 数据模型与迁移 | 10% | Schema 版本化、迁移脚本、回滚策略 |
| 检索与召回路径 | 10% | 检索链路清晰、可插拔、回放能力 |
| 观测与可回放 | 8% | 指标/日志/追踪、DAG 回放、问题定位 |
| 文档与测试 | 7% | 架构/运维文档、单测/集成测试覆盖 |
| 运行与生命周期 | 5% | 资源治理、租户管理、作业编排、任务重试 |
评分规则：每项 0-5 分，按权重加权求和得到总分（满分 100）。
项目评分（0-100）
| 项目 | 架构 | 插件化 | 配置 | 构建 | 数据 | 检索 | 观测 | 文档 | 运行 | 总分 |
|---|---|---|---|---|---|---|---|---|---|---|
| onyx | 4.6 | 4.7 | 4.3 | 4.2 | 4.4 | 4.5 | 4.7 | 4.2 | 4.5 | 91 |
| LightRAG | 4.4 | 4.5 | 4.0 | 4.1 | 4.0 | 4.4 | 3.8 | 4.2 | 3.9 | 84 |
| RAG-Anything | 4.2 | 4.3 | 3.8 | 4.0 | 3.9 | 4.4 | 3.7 | 4.0 | 3.8 | 82 |
| SurfSense | 4.3 | 4.2 | 4.0 | 4.2 | 3.8 | 4.5 | 3.9 | 4.0 | 3.8 | 83 |
| Verba | 3.9 | 4.1 | 3.9 | 4.3 | 3.6 | 3.9 | 3.5 | 3.7 | 3.6 | 76 |
| ragflow | 4.0 | 3.8 | 3.6 | 4.1 | 3.7 | 4.2 | 3.6 | 3.5 | 3.8 | 75 |
| UltraRAG | 3.7 | 3.9 | 3.6 | 3.8 | 3.4 | 3.7 | 3.3 | 3.3 | 3.3 | 69 |
注：评分依据公开实现可验证项与落地经验，供选型参考。
打分依据与证据
onyx（企业级基座）
- 架构与边界：API/Workflow/Auth/Index/Retrieval 模块清晰，LangGraph 编排明确
- 插件化：向量库/Embedding/LLM/Connectors 可插拔，租户隔离策略明确
- 观测与回放：结构化日志 + 指标 + 审计，DAG 可回放与任务重试完善
- 风险与代价：工程化复杂度高，配置维度多（租户/权限/工作流），学习曲线陡
LightRAG（通用 + 二开友好）
- 架构与边界：双层检索（向量/图谱）与清晰目录，扩展点丰富（存储/图谱/检索）
- 插件化：多后端存储与检索实现，Prompt/生成可替换
- 风险与代价：图谱质量与维护成本，复杂模式调优需要经验
RAG-Anything（多模态增强）
- 架构与边界：在 LightRAG 上增强解析/多模态链路（图像/表格/公式）
- 插件化：多模态解析器/模板可替换，缓存体系友好
- 风险与代价：模板维护与模型依赖（VLM/OCR/表格识别）
SurfSense（混合检索 + 重排）
- 架构与边界：向量 + BM25 + RRF，FlashRank/BGE 重排链路清晰
- 插件化：检索器/重排器可插拔，PostgreSQL 原生混检示例完善
- 风险与代价：依赖较多（爬取/清洗/检索），需要统一配置与监控
风险清单与缓解策略
- 配置爆炸（多租户/多环境/多模型）→ 配置分层（env/tenant/feature），默认模板 + 校验
- 索引一致性（异步任务失败/重复导入）→ 幂等键、任务状态机、死信队列 + 回放工具
- 观察性不足（难定位问题）→ 统一 Request-ID、DAG 追踪、采样慢查询
- 模型替换风险（API 差异）→ 模型适配层（统一接口），金丝雀发布
选型建议（按团队与需求）
- 企业级上线（权限/审计/工作流）→ onyx（优选）
- 通用研发 + 快速二开 → LightRAG（起步），按需引入 RAG-Anything 多模态
- 学术/抓取场景 → SurfSense（混合检索 + 重排链路完整）
- 快速验证/低门槛 → Verba（接口简单、易替换）
落地清单（Checklists）
- 明确二开点：检索/索引/解析/生成/Agent 哪些需要自定义
- 评估数据模型变化：新增字段/索引迁移/兼容策略
- 建立回放与沙箱：请求/检索/生成全链路回放
- 设定非功能性目标：P95 延迟、QPS、SLA、成本上限
- 上线流程：蓝绿/金丝雀 + 指标告警 + 回滚脚本
结论
- ≥ 85 分：可作为企业底座（onyx 91）
- 70 ~ 85 分：适合专项或二次集成（LightRAG/SurfSense/RAG-Anything）
- < 70 分：研究/验证为主（UltraRAG）