企业官网建设流程全解析

Mosaico 是面向机器人与 Physical AI 的开源数据平台。本教程带你用最快的方式完成 mosaicod 守护进程安装，并通过 Python SDK（mosaicolabs）在 5 分钟内建立第一条连接，列出你的第一组 Sequence。整个过程只需要两个组件：服务端mosaicod+ 客户端mosaicolabs。

先看懂 Mosaico 的双组件架构

Mosaico 采用经典的客户端-服务器模型，你只需记住下面两个角色：

没有运行中的mosaicod，任何客户端调用都不会成功。所以本文顺序是：先装 daemon，再装 SDK，最后连接。

两个组件之间基于 Apache Arrow 列式格式传输数据，实现零拷贝交换，这也是 Mosaico 相比.bag/.mcap单体文件能高效随机检索的关键。

5分钟环境准备：Mosaico 系统要求

开始之前，确认你的环境满足以下条件：

• 操作系统：Linux 或 macOS（Windows 用户请先安装 WSL2 + Ubuntu，然后在其中操作）
• Python：3.10 或更高版本
• Docker：可选，仅在使用容器方式部署mosaicod时需要
• 端口：mosaicod默认监听6726端口，请确保未被占用

一键安装mosaicod：两种快速方法

方法一：官方一行安装脚本（推荐新手）

最快的方式是执行官方安装脚本，它会自动装好mosaicod与配套命令：

curl -fsSL https://get.mosaico.dev | sh

脚本结束后你会得到：

• 可用的mosaicod和mosaicoctl命令
• 手册页面，可通过man mosaico查看
• 可选安装的 Python SDK

💡 建议先以 dry-run 模式预览脚本将执行的每一步，不做任何磁盘修改：

curl -fsSL https://get.mosaico.dev | sh -s -- --dry-run

方法二：Docker Compose 容器化部署

如果你更喜欢自己管理容器，可以用一个精简的 compose 文件快速拉起mosaicod+ PostgreSQL：

services: db: image: postgres:18 environment: POSTGRES_HOST_AUTH_METHOD: trust mosaicod: image: ghcr.io/mosaico-labs/mosaicod:latest environment: MOSAICOD_DB_URL: postgresql://db:5432/postgres MOSAICOD_DB_USER: postgres MOSAICOD_STORE_ENDPOINT: file:///tmp MOSAICOD_STORE_BUCKET: mosaico command: server --host 0.0.0.0 depends_on: - db ports: - "6726:6726"

该配置会在本机/tmp/mosaico生成数据目录，可通过MOSAICOD_STORE_ENDPOINT修改。如需包含 cleanup、store-optimizer 等后台维护任务的完整生产级配置，可参考 docs/main/docs/daemon/install.md 中的标准 compose 文件，开发环境配置见 docker/devel/compose.yml。

验证 daemon 是否正常运行

安装完成后，用ps子命令查看已注册的mosaicod实例（该命令会同时汇总清理例程状态）：

mosaicod ps

命令的完整参数说明可参考 docs/main/docs/daemon/cli.md。如果输出中出现 server 实例记录，说明守护进程已就绪。

快速安装Python SDK：一条pip命令

确认mosaicod在运行后，安装客户端 SDK 只需一条命令：

pip install mosaicolabs

mosaicolabs提供了完整数据生命周期的高层 API：摄入传感器数据、查询目录、把数据直接流式拉进 ML 流水线，无需任何自定义序列化代码。SDK 客户端入口是MosaicoClient.connect()工厂方法（唯一推荐的实例化方式，直接__init__会抛出RuntimeError），实现位于 mosaico_client.py。

完成第一次Mosaico连接：MosaicoClient 完整示例

现在，用下面的脚本连接本地守护进程并列出所有 Sequence：

from mosaicolabs import MosaicoClient # 连接本地 Mosaico 服务器 with MosaicoClient.connect(host="localhost", port=6726) as client: # 列出所有可用的 Sequence sequences = client.list_sequences() print(f"Connected! Found sequences: {sequences}")

几个关键细节：

• MosaicoClient.connect()建立到指定 host/port 的 gRPC 通道，可选参数还包括timeout、enable_tls、api_key等
• 作为上下文管理器使用，可确保连接在任何异常情况下都被干净关闭
• list_sequences()返回字符串列表（实现在 mosaico_client.py）。全新实例输出Connected! Found sequences: []是完全正常的——空列表本身就证明连接成功了 ✅

连接成功后：把第一条数据写进去

连接打通后，建议立即写入一条数据验证全链路。写入流程遵循三层结构：Sequence → Topic → Message，三步走：

1. client.sequence_create()创建一个录制会话，返回SequenceWriter
2. swriter.topic_create()绑定一个 Ontology 类型（如内置的IMU），返回TopicWriter
3. 循环调用push()推送带纳秒时间戳的Message

Mosaico 的 Ontology 类型系统会自动为内置类型（IMU、GPS、Pressure等）完成校验与 Arrow 列式存储，自定义传感器类型也可以零改动地融入：

完整可运行的 CSV 摄入示例（含三层错误处理策略）见 docs/main/docs/learn/writing_single_topic.mdx。

常见陷阱：mosaicod连接失败排查清单

第一次连接失败大多出在下面几处，按表自查即可：

下一步：从连接到数据流水线

打通第一次连接后，建议按这条路径继续：

• 写数据：单 Topic 摄入、多 Topic 交错写入，见 learn/ 指南目录
• 查数据：按时间窗口、Topic 过滤查询 Sequence，同样在 learn 目录下有专题教程
• 对接 ROS / MCAP：SDK 内置 Bridge 可直接转换 ROS bag 与 MCAP 文件，把非同步的传感器流自动整理为张量就绪的训练批次

🎉 恭喜！你已用 5 分钟跑通了 Mosaico 的核心链路：安装 mosaicod → 安装 Python SDK → 完成第一次连接。接下来就是把你的真实传感器数据灌进去吧。