CodataAdmin

企业级语义治理与可信取数平台：把物理数仓建模为分层语义本体，经人工审核与发布快照后，通过 MCP 向 AI Agent 提供有口径背书的取数能力。

简体中文 | English

配套项目：本仓库是 Codata 项目的配套语义模型项目，专注语义建模、发布快照与 MCP 可信取数；平台与 Agent 能力请见 Mlilion/Codata。

在线体验 Demo

在线体验地址及体验账号在交流群内提供，请前往联系方式扫码进群获取。若群二维码已过期，可添加作者微信，由作者邀请入群。

项目定位

CodataAdmin 的核心不是后台管理，而是语义模型。它要回答三个问题：

1. 业务语言里的「订阅收入」「活跃用户」在物理数仓里到底对应什么？
2. 这个数字按什么口径计算、由谁维护、改完会影响谁？
3. AI Agent 如何在不写 SQL、不猜口径的前提下，拿到可解释、可审计的数字？

平台围绕这三个问题提供一条完整链路：

物理目录 → 分层语义本体 → 语义模型组装 → 发布快照 → 检索索引 → MCP 取数 → 审计闭环

用户、角色、租户、菜单等后台能力只作为治理流程的运行底座，不是本项目的主体。

语义本体架构

语义中心按 L1–L6 分层组织（代码中的 OneData 本体 分层），语义模型是这些资产的组装与发布单元。

flowchart TB
    subgraph L1["L1 物理目录"]
        DS[数据源] --> DB[物理库] --> TB[物理表] --> CL[物理列]
    end

    subgraph L2["L2 业务语义"]
        DM[业务域]
        EN[业务实体] --> FD[业务字段]
    end
    TB -->|physical_table_id| EN
    CL -->|physical_column_id / expr| FD

    subgraph L3["L3 实体关系"]
        JN["JOIN 关系图<br/>from / to / on_expr / relationship"]
    end
    EN <--> JN

    subgraph L4["L4 维度"]
        DI["语义维度<br/>bind_entity + bind_field"]
    end
    DI --> EN

    subgraph L5["L5 指标"]
        IN["语义指标<br/>主实体 + 可用维度白名单"] --> IM["口径 SQL<br/>primary / secondary"]
    end
    IN --> EN

    subgraph L6["L6 知识"]
        KN[知识条目] --> KR[交叉引用]
    end
    KR -.->|refs| EN
    KR -.->|refs| FD
    KR -.->|refs| DI
    KR -.->|refs| IN
    KR -.->|refs| JN

    subgraph ASM["组装与发布"]
        MD[语义模型] --> ME[模型成员]
        MD --> RL["Release 快照<br/>版本化 JSON"]
    end
    EN --> ME
    DM --> MD
    DI --> RL
    IN --> RL
    JN --> RL
    KN --> RL
    RL --> IDX["检索副库<br/>PostgreSQL + pgvector"]
    RL --> MCP["MCP Server"]
    IDX --> MCP

分层职责

本体关系

• 实体 → 物理表：多对一，软外键；物理表被删除时置空并标记 orphan，而不是级联删除语义资产。
• 字段 → 物理列：多对一；非直接映射时用 expr 保存计算式。
• 维度 → 实体字段：维度必须绑定到具体实体上的具体字段，发布时校验绑定是否仍有效。
• 指标 → 主实体 + 口径：一个指标归属一个主实体，可有多条 SQL 口径；只有 primary 且审核通过的口径会进入发布快照。
• 知识 → 任意节点：一条知识可同时挂到实体、字段、维度、指标、JOIN 或模型上，发布时跟随挂载位置进入快照。
• 模型 ↔ 实体：多对多，模型只圈成员、不拥有实体，因此维表实体可被多个模型复用。

发布：进入 Agent 视野的唯一入口

语义模型发布不是一个按钮，而是整条链路的编译与门禁：

1. 组装模型树：选定成员实体，标记 primary / related，关联维度、指标、JOIN 与知识。
2. 完整度检查：红灯阻断发布——实体未绑定有效物理表、字段未绑定物理列、维度未绑定实体字段、已发布指标无审核通过的主口径、JOIN 端点缺失或未发布、知识未发布、模型无成员实体；黄灯仅提示——缺粒度、缺负责人、未设主实体、未声明可用维度、实体或指标未发布等。
3. 编译快照：只收录「已发布」状态的节点；hidden 字段不进入快照；只带审核通过的口径；知识按 usage_mode 处理——always 内联全文、auto 留摘要索引并把正文放入 knowledge_pool、never 不进快照。
4. 发布审计：
   • 口径 SQL 不得引用模型未声明的列（防止上游改表后发布「全绿」、取数才报错）；
   • 口径 SQL 必须兼容当前目标方言；
   • 任一红灯都会拒绝发布，不降级、不放行。
5. 版本递增：version + 1，写入快照与 checksum，模型状态置为已发布。
6. 同步检索索引：把新快照编译进 PostgreSQL 检索副库。索引同步失败只告警，不回滚发布——检索是可选增强，不能拖垮主链路。

发布快照的结构是稳定的消费契约：

{
  "model":       { "code": "...", "name": "...", "version": 7, "domain": "...", "default_time_grain": "month" },
  "entities":    [{ "code": "...", "physical": { "datasource": "...", "database": "...", "table": "..." }, "fields": [] }],
  "dimensions":  [{ "code": "...", "bindings": [{ "entity": "...", "field": "..." }] }],
  "indicators":  [{ "code": "...", "primary_entity": "...", "impls": [], "available_dimensions": [] }],
  "joins":       [{ "from_entity": "...", "to_entity": "...", "on_expr": "...", "relationship": "many_to_one" }],
  "model_knowledge": [],
  "knowledge_pool":  {}
}

没有发布快照，就没有权威口径。 检索会跳过该模型，hydrate 会报错，取数会返回 model_not_released。

在线取数链路

用户问题
  → 预处理：剥离时间窗
  → 检索：定位指标 / 维度 / 知识
  → hydrate：从 Release 快照取权威口径
  → 意图校验：确定性规则夹住 LLM 的自由度
  → 填参 / JOIN 编译：把时间窗、维度、过滤条件安全地放进口径 SQL
  → 只读执行：只读账号 + LIMIT + EXPLAIN 预检
  → 口径声明：返回数字时必须同时返回口径与风险提示

分级检索

检索副库是派生索引，主库 MySQL 仍是唯一事实源。索引按四级递进打分，同一节点多路命中取最高分、不累加：

检索明确区分三种「没有结果」：候选歧义要求用户用 code 指定；覆盖范围外返回 rejected；服务端故障返回 unavailable。三者语义相反，绝不混为一谈。

意图校验

校验器是幻觉的最后一道闸，用确定性规则约束自然语言转出的结构化意图：

• 维度必须在该指标的可用维度白名单内；
• 过滤值必须落在字段的 enum_values 内；
• 指标类查询必须有时间窗，防止全表扫描；
• 草稿口径不得被当作权威口径使用；
• 时间窗跨越口径分水岭时拒绝（跨分水岭汇总会虚高）；
• 订单级 / 快照级指标不得误用 DWD 明细层；
• order_by / top_n / data_layer 都有明确的合法取值与边界。

任一规则不通过，返回结构化错误（rule / message / allowed），让 Agent 反思或向用户澄清，而不是放行一条错 SQL。

跨实体下钻

维度可以不在指标的主实体上。系统会按 sem_join 中登记的关系自动关联一跳并重建 SQL，口径条件原样保留。这条路宁可拒绝，也不猜：

• 经一对多关系做 SUM / AVG / COUNT(*) → fanout_refused（行数放大，数字会虚增且 SQL 不报错）；
• 口径含 CTE、子查询、多表、多聚合或自带 GROUP BY → not_decomposable；
• 多跳、多个跨实体维度、跨实体维度叠加过滤 → 显式拒绝。

拒绝就是答案。 这些错误表示「这个数按这个维度拆出来会是错的」，换相近指标凑数比返回失败更糟。

MCP 工具

MCP Server 以 Streamable HTTP 暴露在 /mcp，标准流程：

list_models → search_semantic → get_model_context → query_indicator
                                                    └→ execute_sql（仅探索/核对）

鉴权与隔离：MCP Token 可绑定平台用户；public 模型对所有调用方可见，restricted 模型仅模型负责人、被授权用户与超管可见。越权统一返回 model_forbidden，不暴露模型是否存在。

语义中心（Web 管理台）

此外提供运维自检接口 GET /api/v1/semantic/retrieval/readiness：检查模型是否发布、索引是否过期、数仓是否连通、MCP 是否挂载、是否有高影响上游变更。blockers 为空才算就绪。

技术栈

语义检索副库、嵌入模型、DataCatalog 同步与 MCP 接入都是可选能力；不开启时平台仍可完成建模、发布与后台治理，只是检索降级为仅使用 always 档知识。

快速启动

环境要求

• Python 3.12+ 与 uv
• Node.js 20.19+ 与 pnpm 9.x
• MySQL 8.0+ 与 Redis

启动

# 后端
cp backend/env/.env.dev.example backend/env/.env.dev
cd backend
uv sync
uv run main.py init-db --env=dev      # 首次初始化表与基础数据
uv run main.py run --env=dev

# 前端
cp frontend/web/.env.example frontend/web/.env
cd frontend/web
corepack enable
pnpm install
pnpm dev

打开 http://127.0.0.1:5180/web/#/login。开发环境演示账号为 super / admin / user，默认密码 123456，仅供本地使用；生产环境必须在首次初始化前通过 INITIAL_ADMIN_PASSWORD 设置至少 16 位管理员密码。

语义检索副库启用后，初始化其表结构：

cd backend
uv run main.py init-retrieval --env=dev

Docker 部署、Nginx 与生产配置见 docker/README.md 和根目录 deploy.sh。

语义相关配置

SEM_RAW_SQL_ENABLE 的边界在数仓账号授权上，不在应用层。若依赖模型级可见性做数据隔离，不要开启它。

目录结构

.
├── backend/
│   ├── app/api/v1/module_semantic/   # 语义中心：目录、域、实体、关系、维度、指标、知识、模型、检索、MCP
│   ├── app/scripts/data/             # 初始化数据
│   └── docs/                         # 语义部署清单与 MCP 接入说明
├── frontend/web/                     # Vue 3 Web 管理台（语义中心页面）
├── frontend/app/                     # 预留移动端目录
├── frontend/docs/                    # 预留文档目录
├── docker/                           # Compose、MySQL/Redis/PostgreSQL、Nginx
├── docs/images/                      # README 配图（交流群与作者二维码）
└── deploy.sh                         # 一键部署脚本

语义模块的关键子目录：

backend/app/api/v1/module_semantic/
├── catalog/      # L1 物理目录、DataCatalog 同步、上游变更
├── domain/       # 业务域
├── entity/       # 业务实体与业务字段
├── join/         # 实体关系
├── dimension/    # 维度
├── indicator/    # 指标与 SQL 口径
├── knowledge/    # 知识条目与交叉引用
├── model/        # 模型组装、完整度、发布快照
├── retrieval/    # 检索、hydrate、校验、填参、JOIN 编译、只读执行
└── mcp/          # MCP Server 与鉴权

文档入口

• 后端说明
• 前端 Web 说明
• Docker 部署说明
• 语义部署清单
• MCP 接入与取数规则
• 飞书 OAuth 说明

许可证

本项目以 GNU GPL v3.0（GPL-3.0-only）授权，详见 LICENSE。

部署提醒

• 生产环境不要沿用初始化账号、默认密码或示例密钥。
• 主库以 ORM 与 JSON 种子为初始化来源；语义检索副库是可重建的派生索引，不是事实源。
• 语义模型必须发布后才会被 MCP 工具列出和消费。
• 发布门禁与就绪自检是两道独立防线：前者拦截「不能进入快照」，后者回答「这套东西现在能不能用」。

联系方式

欢迎进群讨论、反馈问题或交流语义建模实践。

• Codata Agent 交流群：扫码加入。群二维码 7 天内有效；若已过期，请加作者微信，由作者拉你进群。
• 作者微信：扫码添加好友，备注「Codata」，作者会拉你进交流群。

Codata Agent 交流群

作者微信（moilion）