models/          # 表定义 JSON（11 张 rag_ 前缀表）
json/            # 部分表的 UI/CRUD JSON 定义
init/            # uapi_seed.sql（uapi 种子）、migrate_rag_prefix.sql（旧表加前缀迁移，幂等）
rag/             # Python 包：init.py（DSPY handler 注册）、api_core.py、pipeline.py、
                 #   ingest.py、vl_online.py（在线 embedding/rerank + VDB 直调）等
scripts/         # load_path.py（RBAC 路径注册，宿主 load_path.sh 自动扫描调用）
wwwroot/         # 前端页面与 DSPY 端点
  api/           #   对外 B2B API（kb_create/doc_upload/search/tag_* 等 .dspy）
  knowledge_bases_list/  # 知识库管理主页面（index.ui + 全套 .dspy）
  documents_list/ engine_configs_list/ subscriptions_list/
build/           # 打包产物（勿手改）

后端注册：rag/init.py 通过 appPublic.registerfunction.RegisterFunction 注册全部 DSPY handler（kb_list、search、doc_upload、doc_delete、dir_*、tag_*、engine_options、status 等）。宿主入口调用规范名 load_rag()（旧名 init_rag_module 保留为别名，ragserver 等旧宿主无需改动）。

表清单（rag_ 前缀）

模块跨应用复用，所有表统一加 rag_ 前缀，避免与宿主业务表冲突（旧无前缀表可用 init/migrate_rag_prefix.sql 幂等改名迁移）。

表名	用途
`rag_knowledge_bases`	知识库主表（含 `embedding_engine`、`vdb_collection`、存储占用等）
`rag_documents`	文档/媒体文件（含 metadata JSON，存标签、声纹状态、位置信息等）
`rag_document_chunks`	文档分片（metadata 存 bbox、start_time/end_time 等位置信息）
`rag_engine_configs`	引擎配置（engine_type/endpoint_url/api_key/model_name，按 org 隔离）
`rag_entities`	NER 抽取的实体
`rag_entity_relations`	实体关系（图谱边）
`rag_tags`	标签定义
`rag_media_tags`	媒体-标签关联（与 documents.metadata.tags 双源存储，展示需去重）
`rag_subscriptions`	租户订阅（磁盘/文档/知识库/API 调用四类配额与用量）
`rag_org_storage_limits`	机构存储限额
`rag_usage_logs`	用量日志（计费/审计）

embedding_engine 机制

向量化引擎在创建知识库时选定（rag_knowledge_bases.embedding_engine），库内所有文档统一使用该引擎：

bge-m3 — 文本知识库，1024 维，走阿里在线服务；
clip-vith14 / qwen3-vl-embedding — 多媒体知识库（图/音/视），后者 2560 维。

GPU 已于 2026-09 退役，embedding / rerank 全部走阿里在线接口（rag/vl_online.py），不再依赖本地 CLIP/BGE GPU 服务。字段默认值 clip-vith14 是历史遗留，新建库应显式选择在线引擎。

与 uapi 模块的依赖和建表顺序

rag 的外部服务（embedding、rerank、VDB、NER、人脸、图谱、声纹）统一通过宿主的 uapi 模块路由，服务地址配置在 upapp / uapi / uapiio 表中。因此必须先有 uapi 表，才能插入 rag 的服务种子。

标准 build.sh 顺序：

先建 uapi 模块的表（upapp/uapi/uapiio 等）；
再建 rag 模块的表（models/*.json）；
最后导入 init/uapi_seed.sql（INSERT IGNORE 幂等），写入 rag-embedding、rag-reranker、rag-vdb、rag-ner、rag-face、rag-graph、rag-voiceprint 等服务配置。

顺序颠倒会导致 uapi_seed.sql 因目标表不存在而失败。

VDB 连接配置

VDB（Milvus 向量库）地址不硬编码，运行时从 upapp 表读取：

SELECT baseurl FROM upapp WHERE id='rag-vdb';

见 rag/vl_online.py 的 vdb_baseurl() / vdb_call()（HTTP 直调 /v1/createcollection、/v1/upsert、/v1/search、/v1/delete）。

生产内网：192.168.16.10:9186
测试内网：192.168.16.10:9187

uapi_seed.sql 中种子默认是公网域名（vectordb.opencomputing.net:10443），部署到新环境后需按实际网络把 upapp.rag-vdb 的 baseurl 更新为对应内网地址。

与 ragserver 的关系

ragserver 是一个宿主应用（/d/rag/ragserver，进程 app/ragserver.py，域名 rag.opencomputing.cn），本仓库作为 pkgs/rag 挂载其中；
同一份代码也挂载到 pipeline-app（pkgs/rag，DB pipeline，菜单「知识库」）；
同代码、不同宿主、各自数据：每个宿主用自己的库建 rag_ 表和 uapi 种子，数据互不共享。

部署注意

RBAC 路径注册：部署后在宿主根目录执行 py3/bin/python pkgs/rag/scripts/load_path.py（pipeline-app 的 load_path.sh 会自动扫描）。对外 B2B API 端点走 cookie 会话或 Authorization: Bearer <dapi key> 鉴权，org 隔离在 rag/api_core.py 内强制。
新增 .dspy 必须补 RBAC：permission 表 + rolepermission 表（roleid='any'，外键列名是 permid）两条都缺一个就 403，补完重启宿主进程。
建表顺序：uapi 表 → rag 表 → uapi_seed.sql（见上文）。
DSPY 热加载：宿主 hot_reload=True 时改 .dspy 无需重启；改 Python 包（rag/*.py）需重启进程。
旧环境迁移：无前缀旧表用 init/migrate_rag_prefix.sql 幂等改名，不要手工 RENAME。
删除知识库/文档要清全链路：DB 行、VDB 向量、图数据库、实体/关系、物理文件都要清理，只删 DB 会留脏数据。
sqlor 陷阱：SQL 中字面 % 需写成 %%；IN (${ids}$) 列表展开在 rag 服务器的 sqlor 版本不可用，需手工拼引号字符串。
代理陷阱：StreamHttpClient 默认走 socks5://127.0.0.1:1086，测试/生产机无此代理时直连超时，排查 VDB/在线服务不可达先确认代理。

README.md Unescape Escape

rag — RAG 知识库管理模块

目录结构