在 Agent 里使用 Dosi¶
要让 AI Agent 回答数据问题,有两条路。一条是把数仓 schema 喂给它、让它自己写 SQL,也就是常说的 NL2SQL;另一条是调用一个已经知道指标含义的语义层。Dosi 给 Agent 的是第二条:发现你的指标,编译成数仓 SQL,再执行。
两种接入方式¶
| Dosi 插件 | 自己启动 MCP 服务 | |
|---|---|---|
| 适用于 | Claude Code、Codex、DeepSeek Harness;其他 Agent 可以只装 skill | 任何 MCP 客户端 |
| 得到什么 | 自动装好 dosi,负责连接、建模、问数的 skill,dosi 的 MCP 工具,以及不让口令进入对话的钩子 | dosi 的 MCP 工具 |
| 怎么接 | 装一次插件 | 装 dosi、启动服务、注册到客户端、加上提示词规则 |
你的 Agent 有插件就先用插件:快速上手一句话装好插件,然后连上示例数据库, 建模型,提问,十分钟以内。
Agent 拿到了什么¶
工具分五组,用的都是 CLI 和 REST API 那套查询形状:
| 阶段 | 工具 | Agent 由此得知或能做什么 |
|---|---|---|
| 发现 | list_metrics、list_dimensions、list_datasets、describe_metric、describe_dataset、list_connections |
有哪些指标、各自怎么算出来、能按哪些字段拆分、这些字段什么含义 |
| 预览 | compile_sql、explain_query、compile_select、explain_select(按需列出) |
将要执行的 SQL 或执行计划,执行之前就能看到 |
| 执行 | run_query、select、attribute_metrics、attribute_dimensions |
指标结果、明细记录,以及指标为什么变了:先按公式拆,再按分组拆 |
| 编写 | validate_model |
一次模型改动在服务端引擎模式下是否合法 |
| 本体 | describe、paths |
加载了本体时,业务概念以及概念之间的路径 |
词表小而封闭:指标有名字,group_by 字段写成 dataset.field(外加保留的
metric_time)。只要 Agent 待在这个词表里,就编不出一个不存在的列,也不会悄悄
选错表。每个工具的说明见 MCP 参考。
为什么比裸 schema 的 NL2SQL 更准¶
论点不是"模型写不好 SQL",而是:一个业务问题对应的正确 SQL,无法从列名推导出
来。这份知识必须有人先写下来一次——这正是语义模型的作用。由此有四点区别,都能
在自带的 orders 示例上看到。
口径由模型定,不靠猜¶
orders 模型里的 revenue 是 SUM(orders.amount),覆盖全部订单,取消的也
算。只给表权限的 Agent 被问到"总营收",通常会补一句 WHERE status = 'completed'
——这个猜测很合理,但答案不一样:350,而不是 450。两条 SQL 都不算错,只有一
条符合公司对营收的定义。走指标层,所有 Agent、看板、notebook 拿到同一个数,而定
义写在 YAML 里可评审,不必每问一次就重新发明一遍。
不会跨表重复计数¶
total_margin 的定义是 SUM(orders.amount) - SUM(products.unit_cost):两个聚
合,分别落在两张表上。Dosi 的编译方式是先各自聚合,再合并:
WITH m0 AS (SELECT SUM(orders.amount) AS orders_amount_sum FROM orders AS orders),
m1 AS (SELECT SUM(products.unit_cost) AS products_unit_cost_sum FROM products AS products)
SELECT m0.orders_amount_sum - m1.products_unit_cost_sum AS total_margin
FROM m0 CROSS JOIN m1
结果是 360。而手写时最自然的写法——先把 orders 连到 products,再
SUM(o.amount - p.unit_cost)——得到 270:连接让每个商品行按订单数重复,成本
那一侧被放大了。这就是不会静默重复计数那条保证在起
作用:扇出(fan-out)是连接图的性质,Agent 从 schema dump 里看不出来。
粒度和去重不会搞错¶
unique_customers 的定义是 COUNT(DISTINCT orders.customer_id)。按月拆分,示例
数据上是 1 / 2 / 1;换成普通的 COUNT(customer_id) 就变成 2 / 3 / 1。这个区别写
在指标定义里,Agent 不必重新发现,也就不会漏掉。
换数仓不用改问题¶
同一个请求会按目标方言编译成该数仓真正支持的写法:DuckDB 得到
DATE_TRUNC('MONTH', …),而 MySQL 没有 DATE_TRUNC,得到的是
STR_TO_DATE(DATE_FORMAT(…, '%Y-%m-01'), '%Y-%m-%d')。手写 SQL 的 Agent 得记住
每种数仓的日期写法;调 compile_sql 的只需要换一个 dialect。
代价是什么¶
做这件事的理由是准确率。成本这一侧比通常的宣传更微妙,这里写实测结果,而不是写 着好听的说法。
有两项确实变便宜了:
- 编译发生在 Rust 里,不烧 token。规划连接图、渲染方言 SQL 大约一毫秒,在模 型之外完成——实测且确定。
- Agent 不再探查数据。裸 SQL 的会话里,
SELECT DISTINCT status、LIMIT 5试探、"这列是不是编码"之类的确认要花掉不少轮次。走指标层没什么可探的;名字写 错时错误里直接带candidates,一轮改对,而不是进入一段调试循环。
但有一项不便宜,做预算前值得知道:在 小 schema 上,MCP 这条路吃掉的模型上 下文更多,不是更少。工具的定义(含完整的指标查询形状)是每次调用都要付 的固定成本,在示例这种三张表的模型上,它比整份 schema dump 还大。我们自己的实测 里,语义层这一臂在该 fixture 上轮次更多、上下文更大。
这笔账会随数仓变大而反转:工具表面积恒定,schema dump 随列数增长,探查轮次随编 码列增长。所以"更省"是你自己 schema 规模的函数,需要用你自己的问题实测。
它解决不了什么¶
把边界说清楚,因为这些才决定它适不适合你:
- 从措辞映射到指标名,仍然是 Agent 的活。
list_metrics暴露的是指标名和描 述,还没有投影 Apache Ossie 模型里的ai_context同义词,所以一个说法只要在名字和 描述里都没出现过,就仍然可能对不上。 - 模型没覆盖的问题,用这些工具答不出来。这是刻意的——拒答好过一个自信的错 数——但也意味着模型的覆盖面就是你的覆盖面。探索性的查询,还是留给裸 SQL。
- 定义错了就到处都错。定义集中,爆炸半径也集中:把
model.yaml当作要评审 的代码,并在 CI 里跑dosi validate。
下一步¶
-
在 Claude Code、Codex、DeepSeek Harness 或其他 Agent 里安装。
-
从空目录到在 20 万条订单上得到答案,大约十分钟。
-
适用于任何 MCP 客户端:启动服务、注册,并设定 Agent 能做什么。