跳转至

在 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。

下一步

  • Dosi 插件


    在 Claude Code、Codex、DeepSeek Harness 或其他 Agent 里安装。

  • 快速上手


    从空目录到在 20 万条订单上得到答案,大约十分钟。

  • 自己启动 MCP 服务


    适用于任何 MCP 客户端:启动服务、注册,并设定 Agent 能做什么。