跳转至

安装 Dosi

一条命令就能在 Linux 或 macOS 上装好 dosi 和 dosi-server，不需要另外装任何东西： 不需要工具链、不需要数据库、不需要客户端库。

$ curl -fsSL https://dosi.datus.ai/install.sh | DOSI_SOURCE=oss sh

$ curl -fsSL https://dosi.datus.ai/install.sh | DOSI_SOURCE=oss DOSI_SHAPE=lean sh

$ curl -fsSL https://dosi.datus.ai/install.sh | sh

$ pip install dosi-engine

需要 Python 3.12+，见 Python 绑定。

装完检查一下：

$ dosi --version
dosi 0.1.12

拿不准选哪个？选默认版。精简版是给没有 C++ 运行时的机器用的，两者区别见 该下载哪个？。不想把脚本直接管道给 sh，可以走 手动下载。想确认它能读模型，接着看验证是否可用。

安装脚本做了什么

脚本会识别你的 CPU，下载对应的归档，校验它的 SHA-256， 然后把 dosi 和 dosi-server 装到 ~/.local/bin——默认版还会把 libduckdb.so 一并放在旁边。如果这个目录还不在 PATH 上，记得加进去。

之后想换版本，重新跑一次脚本即可（加或不加 DOSI_SHAPE=lean），它会直接覆盖。 从默认版换到精简版会留下一个用不到的 libduckdb.so，无害——想省空间可以删掉。

示例模型会跟着一起装到 ~/.local/share/dosi/examples， 脚本结束时会把路径打出来。

不传 DOSI_SOURCE 时脚本的 manifest 和归档都默认从 GitHub 取；上面的命令 额外传了 DOSI_SOURCE=oss，两者都改从阿里云 OSS 镜像取——国内网络通常快 很多。两个源之间不会自动切换：选中的源失败，脚本直接报错退出，不会 偷偷换一个源重试。校验和仍然是防线：不管走哪个源，下载下来的归档都要通过 同一份 manifest 里记录的 SHA-256 校验，只是这份 manifest 现在也跟着 DOSI_SOURCE 走，不再固定只从 GitHub 读——普通的传输损坏依然会被校验挡住， 但如果 OSS 镜像本身被攻破，理论上能同时伪造归档和与之匹配的校验和，这一点 上不再像"manifest 固定在 GitHub"时那样绝对可信。DOSI_OSS_MIRROR 可以把 镜像指向内网地址；镜像上归档存放在 v<version>/<file>，manifest 同时存放在 v<version>/manifest.json 和 latest/manifest.json 两处。

该下载哪个？

选默认版。 它是完整形态：精简版能做的它都能做，外加在你的进程内运行 DuckDB 执行本地查询。

选精简版只有一个理由，而且不是体积：默认版要求机器上有 C++ 运行时 （libstdc++ 提供 GLIBCXX_3.4.22，即 GCC 6 及以上），因为 DuckDB 是 C++ 写的。 精简版是纯 Rust 对 libc，完全不需要 C++。如果你的目标环境是 distroless 之类的 精简镜像，或者较老的发行版，这一条就是全部的判断依据。

默认版 精简版
归档 dosi-<version>-<target>.tar.gz dosi-<version>-<target>-lean.tar.gz
本地 DuckDB 查询 进程内，Arrow 原生 调用 PATH 上的 duckdb CLI
文件 dosi、dosi-server、libduckdb.so dosi、dosi-server
机器上还需要什么 glibc ≥ 2.28、libstdc++ glibc ≥ 2.28。仅当要跑本地查询时才需要 duckdb CLI
数仓连接器 全部 全部——完全一致
下载体积 约 63 MB 约 41 MB

其余部分完全相同：同一个编译器、同样的方言、同样的连接器（Postgres、 MySQL/TiDB/StarRocks/Doris、Hologres、DWS、GaussDB、Oracle、ClickHouse、Trino、 Snowflake、BigQuery、Databricks、Arrow Flight）。把指标查询编译成 SQL 两者一模一样， 连数仓执行也一模一样，只有本地 DuckDB 执行不同。

使用默认版

libduckdb.so 必须和 dosi、dosi-server 放在同一个目录——可执行文件是在 自己旁边找这个库的。安装脚本会把三个文件放在一起；手动解压请让它们一起移动， 把 dosi 复制到别处时也要把库一起带上。

使用精简版

本地执行（--execute 配 --db）会调用 PATH 上的 duckdb，需要的话从 duckdb.org 装一个。没有 CLI 时 dosi 照样能编译 SQL、照样能查所有数仓——只是失去本地 DuckDB，真去用会报 cannot start duckdb CLI。

这条路径有两点需要知道：

  • 它是针对 DuckDB v1.4.x 系列验证的，发现 CLI 不在该系列时 dosi 会告警一次。 那条路径的结果经 JSON 回传，所以大整数、DECIMAL、TIMESTAMPTZ 的类型保真度 对版本敏感，默认版的 Arrow 路径没有这个问题。
  • 每条语句起一个新进程，所以内存库在两次调用之间什么都不留。需要保持状态时 请用文件库（--db）。

我装的是哪个？

$ dosi info
dosi       0.1.12
...
build      engine (DuckDB in process)

build 一行会显示 engine 或 lean；dosi info --format json 里对应字段是 shape。

手动下载

Dosi 发布 Linux 和 macOS 版本：

平台 归档 精简版归档
Linux x86_64 dosi-<version>-x86_64-unknown-linux-gnu.tar.gz dosi-<version>-x86_64-unknown-linux-gnu-lean.tar.gz
Linux arm64 dosi-<version>-aarch64-unknown-linux-gnu.tar.gz dosi-<version>-aarch64-unknown-linux-gnu-lean.tar.gz
macOS Apple Silicon dosi-<version>-aarch64-apple-darwin.tar.gz dosi-<version>-aarch64-apple-darwin-lean.tar.gz

并非每个 release 都带上表中的每一行。某个 release 究竟构建了哪些平台，以它的 manifest.json 为准——macOS Intel 尤其只在需要时才构建。安装脚本读的是这个文件， 不去猜文件名，所以缺哪个平台就报 no build for <target>，不会下错归档。

Linux 上可执行文件需要 glibc 2.28 及以上——RHEL/Rocky/Alma 8、Ubuntu 20.04、 Debian 10 以及更新的发行版都可以。默认版还需要 libstdc++ 提供 GLIBCXX_3.4.22 （GCC 6+），这个要求来自 libduckdb；精简版完全没有 C++ 依赖。CentOS 7 低于 这两条下限，在那上面请用容器运行 Dosi。macOS 上的下限是 macOS 11（Big Sur）， 除系统框架外不需要额外安装任何东西。

归档挂在下载仓库每个 release 下。manifest.json 指明当前发布版本， 并带上该版本每个归档的校验和——从 latest 路径取，就不用写死版本号：

$ curl -fsSL https://github.com/Datus-ai/dosi-dist/releases/latest/download/manifest.json

$ VERSION=0.1.12 TARGET=x86_64-unknown-linux-gnu
$ BASE=https://github.com/Datus-ai/dosi-dist/releases/download/v$VERSION
$ curl -fsSLO $BASE/dosi-$VERSION-$TARGET.tar.gz
$ curl -fsSLO $BASE/SHA256SUMS
$ sha256sum --ignore-missing -c SHA256SUMS   # macOS: shasum -a 256 -c SHA256SUMS --ignore-missing
$ tar xzf dosi-$VERSION-$TARGET.tar.gz
$ sudo install dosi-$VERSION-$TARGET/dosi /usr/local/bin/dosi
$ sudo install dosi-$VERSION-$TARGET/dosi-server /usr/local/bin/dosi-server
$ sudo install -m 0644 dosi-$VERSION-$TARGET/libduckdb.so /usr/local/bin/libduckdb.so

最后一行对默认版不是可选的：可执行文件是在自己所在目录找 libduckdb.so 的， 只装两个可执行文件，第一次运行就会报 libduckdb.so: cannot open shared object file。 精简版归档（…-$TARGET-lean.tar.gz）没有这个库，也就没有第三行。

运行之前先校验一遍——SHA256SUMS 覆盖了该版本的每一个归档。

归档里有什么

dosi-<version>-<target>/
├── dosi              CLI
├── dosi-server       REST / Arrow-Flight / MCP 服务
├── libduckdb.so      DuckDB——仅默认版；必须与上面两个可执行文件放在一起
├── LICENSE
└── examples/
    ├── orders/       教程用的模型
    └── tpcds/        CLI 参考用的模型

精简版归档是同样的目录树，只是没有 libduckdb.so。

安装脚本会把两个可执行文件都放到 PATH 上。REST API 和 MCP 服务 两页调用的就是 dosi-server。

验证是否可用

dosi info 不需要模型，所以它同时也是版本探针——它会报告 Apache Ossie 规范版本、 Datus 扩展版本、你装的是哪个版本，以及它认识的 Datus 扩展键：

$ dosi --version
dosi 0.1.12
$ dosi info
dosi       0.1.12
osi spec   0.2.0.dev0
datus-ext  1.9 (accepts 1.0 and up)
mode       datus
build      engine (DuckDB in process)
examples   /home/you/.local/share/dosi/examples
...

要留意的是 examples 这一行：它是内置示例模型的落地位置 —— 用安装脚本装的话是 ~/.local/share/dosi/examples，自己解包的话就是归档里那个 examples/ 目录。 本文档所有页面都通过 $DOSI_EXAMPLES 引用它们，所以先导出一次：

$ export DOSI_EXAMPLES=~/.local/share/dosi/examples

然后拿一份示例模型校验一下：

$ dosi validate --model $DOSI_EXAMPLES/orders/model.yaml
✓ 1 semantic model(s) valid

出现这一行，就可以去看第一个指标查询教程了。

数仓

两个发布版本都包含全部连接器——MySQL/TiDB/StarRocks/Doris、Postgres、Hologres、 DWS、GaussDB/openGauss、Oracle、ClickHouse、Trino、Snowflake、BigQuery、Databricks。 两者的区别只在本地 DuckDB 执行方式（见该下载哪个？）， 与能连哪些数仓无关。各数仓的连接配置（主机、凭据、TLS）见 连接数仓。

为任意方言编译 SQL 从来不需要连接器，它们只在 --execute 时起作用。

Python 绑定

想从 Python 调用 Dosi（模块名 dosi_engine），装 wheel 即可， 需要 Python 3.12+：

$ pip install dosi-engine

快速检查：

$ python -c "from dosi_engine import Engine; print('ok')"
ok

Python API 与 CLI 一一对应：构造 Engine(model_path=…)，再调用 .metrics()、.compile(...)、.execute(...)。（专门的 Python API 参考页在计划中。）

模块级常量说明这个构建实现了哪些能力，内容与 dosi info 一致。 生成模型的工具在决定输出哪些 Datus 扩展键之前，应该先读它：

>>> import dosi_engine
>>> dosi_engine.SPEC_VERSION          # the OSI core spec
'0.2.0.dev0'
>>> dosi_engine.DATUS_EXT_VERSION     # the Datus extension version
'1.10'
>>> [k["key"] for k in dosi_engine.DATUS_EXT["keys"]]
['join_type', 'fill_nulls_with', 'time_dimension', 'time_granularity', 'window',
 'dataset', 'derive', 'measure', 'params', 'time', 'is_dimension',
 'cardinality', 'lod']

DATUS_EXT["keys"] 的每一项还带有引入它的版本号，以及忽略它的代价，见 datus-extensions.md。

Agent 集成可以直接从已安装的 engine 获取完整 authoring contract，不再维护按版本分支的副本：

contract = dosi_engine.DATUS_AUTHORING_CONTRACT
digest = dosi_engine.DATUS_AUTHORING_CONTRACT_DIGEST
prompt_yaml = dosi_engine.render_datus_authoring_spec()

该 contract 不包含方言。当前 Ossie expression dialect 由 datasource 决定，应由宿主单独告诉 Agent；它不属于 engine extension 版本。digest 对相同 contract 内容保持稳定，可用于 prompt cache key。

从 datus_osi_engine 迁移过来

本项目此前叫 osi-engine，Python 包名也随之改动： datus-osi-engine / datus_osi_engine 现已改为 dosi-engine / dosi_engine。 新代码直接 import dosi_engine 即可。

环境变量和连接配置文件也一并改名：OSI_* → DOSI_*、 ./osi-connections.yaml → ./dosi-connections.yaml、 ~/.config/osi/ → ~/.config/dosi/。旧文件路径仍会作为回退被发现 （connectors.md），旧环境变量则不会。 规范本身现已更名为 Apache Ossie（原 OSI）；引擎模式参数 --osi-basic / --osi-datus 和 OSSIE_DIR 保持原名不变。

许可

Dosi 采用 Elastic License 2.0 （ELv2），完整条款在每个归档里的 LICENSE 文件中。你可以免费下载、使用、再分发， 包括生产环境和商业用途。三条限制：不得将 Dosi 作为托管或受管服务提供给第三方、 不得绕过其 license key 机制、不得移除其许可声明。需要托管授权或 ELv2 未涵盖的用法， 请联系 Datus。

下一步