oxen clone https://hub.oxen.ai/ox/CatDogBBox

🤝 支持

如果您有任何问题、意见、建议，或只是想与团队取得联系，请随时发送邮件至 hello@oxen.ai。

👥 贡献

本仓库包含封装核心 Rust 代码库的 Python 库。我们非常欢迎对 Python 接口、文档或核心 Rust 库进行扩展的贡献。

可参与贡献的代码库：

• 🦀 核心 Rust 库
• 🐍 Python 接口
• 📚 文档

如果您正在使用 Oxen.ai 构建项目，或有任何疑问，欢迎加入我们的 Discord 交流。

构建 🔨

每个代码库都有各自的构建说明，请参阅 Rust 构建说明 和 oxen-python 的构建说明 获取详细信息。

不过，所有代码库都共享相同的前置条件和提交前钩子。

先决条件

自动安装

您应该使用 bin/install-prereqs 来自动安装 Rust 和 Python 所需的开发工具和工具链。执行方式如下：

bin/install-prereqs

它支持 macOS 和基于 Debian 的 Linux 发行版。如果您使用的是其他操作系统或发行版，或者在运行安装脚本时遇到问题，您可以按照下面的手动安装步骤进行操作。

手动安装

Oxen 完全由 Rust 🦀 编写。您需要使用 rustup 安装 Rust 工具链。

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安装完 Rust 后，请安装以下开发者工具：

• bacon：带有更改后自动重新加载功能的服务器运行工具
• cargo-machete：用于识别并移除未使用的依赖项
• cargo-llvm-cov：用于计算测试代码覆盖率
• cargo-sort：确保 Cargo.toml 文件的有序性
• cargo-nextest：用于运行单元测试

您可以通过以下命令一次性安装所有这些工具：

cargo install bacon cargo-machete cargo-llvm-cov cargo-sort
cargo install --locked cargo-nextest

请确保已安装 cmake。在 macOS 上，可以使用以下命令安装 CMake：

brew install cmake

Python 接口 使用 PyO3 提供的 liboxen 绑定。

oxen-python 代码库需要安装 uv：

curl --LsSf https://astral.sh/uv/install.sh | sh

如果您使用 mise 来管理您的 Python 安装，可能会遇到 oxen-py crate 无法找到要链接的 Python 动态库的问题，例如 dyld[31558]: Library not loaded: @rpath/libpython3.13.dylib。

您可以通过将以下内容添加到您的 mise 配置文件（~/.config/mise/config.toml）来解决此问题：

[env]
DYLD_LIBRARY_PATH = "{{ exec(command='mise where python') }}/lib"

Pre-Commit 钩子

我们使用 pre-commit-hooks 来检查提交的一致性。

使用 uv 作为工具进行安装：

uv tool install pre-commit

使用以下命令在本地安装 Oxen 的 pre-commit 钩子：

pre-commit install

生产环境发布构建

在部署时，请使用 production 特性标志和 --release 标志进行构建：

cargo build --workspace --release --features production

这将启用：

• OpenTelemetry 跟踪 (otel) -- 将跟踪跨度导出到任何兼容 OTLP 的收集器（Jaeger、Tempo、Datadog 等）。有关运行时配置，请参阅 OpenTelemetry 跟踪。
• FFmpeg 缩略图 (ffmpeg) -- 通过 FFmpeg 生成视频/图像缩略图（需要在主机上安装 FFmpeg 库）。
• 性能日志记录 (perf-logging) -- 用于内部操作的额外计时监控。

如果不使用 --features production，默认构建将排除 OTel 依赖项和 FFmpeg 支持，从而使二进制文件更小，适合本地开发。

日志记录

Oxen 使用 tracing crate 进行结构化日志记录。默认情况下，所有日志输出都会以人类可读的格式发送到 stderr。这适用于 CLI（oxen）、服务器（oxen-server）以及任何使用 liboxen 的代码（包括 Python 绑定）。

控制日志级别

设置 RUST_LOG 环境变量来控制日志的详细程度。

# 显示 oxen 库的调试日志
RUST_LOG=debug oxen push origin main

# 仅显示警告和错误
RUST_LOG=warn oxen-server start

# 细粒度：liboxen 的日志为调试级别，其他部分为警告级别
RUST_LOG=warn,liboxen=debug oxen-server start

使用 OXEN_LOG_DIR 进行文件日志记录

设置 OXEN_LOG_DIR 可以在 stderr 之外启用基于文件的日志记录。该环境变量指定一个目录，用于存放轮转的日志文件。日志文件以 换行分隔的 JSON 格式（每行一个 JSON 对象）写入，并按天轮转。每行包含时间戳、日志级别、目标、线程 ID、源文件和行号。

OXEN_LOG_DIR=./logs/ RUST_LOG=warn oxen clone https://hub.oxen.ai/ox/CatDogBBox
OXEN_LOG_DIR=/var/log/oxen oxen-server start

日志文件在配置的目录中命名为 {app_name}.{date}（例如 oxen-server.2026-04-06）。

要使用标准工具摄取这些日志：

• Promtail / Grafana Loki -- 将 file_sd 或静态目标指向日志目录；Loki 原生支持换行分隔的 JSON。
• Filebeat / Elasticsearch -- 配置一个 filebeat.inputs 条目，设置 type: filestream 和 parsers: [{ ndjson: {} }]。
• Vector -- 使用 file 源，并设置 decoding.codec = "json"。
• jq -- 用于临时检查：

# 流式查看日志，筛选错误
tail -f ~/.oxen/logs/oxen-server.2026-04-06 | jq 'select(.level == "ERROR")'

Prometheus 指标

oxen-server 暴露了一个兼容 Prometheus 的指标端点。 有关详细信息，请参阅 Prometheus 指标。

OpenTelemetry 跟踪

oxen-server 可以将跟踪跨度导出到任何兼容 OTLP 的收集器（Jaeger、Tempo 等）。 需要使用 otel 特性标志进行构建。 有关详细信息，请参阅 OpenTelemetry 跟踪。

FmtSpan 事件

跨度生命周期事件可以作为日志行输出到 stderr，用于轻量级跟踪。 有关详细信息，请参阅 FmtSpan 事件。

为什么构建 Oxen？

Oxen 是由一支机器学习工程师团队构建的，他们在职业生涯中花费了无数时间来管理数据集。我们尝试过许多不同的工具，但没有一个像我们期望的那样易于使用且符合人体工学。

如果您曾经尝试过使用 git lfs 来版本化大型数据集并因此感到沮丧，那么我们深有同感。对于机器学习所需的海量数据来说，像 git-lfs 这样的解决方案速度太慢了。

如果您曾经将大量的图像、音频、视频或文本数据集上传到云存储桶，并为其命名：

s3://data/images_july_2022_final_2_no_really_final.tar.gz

我们构建 Oxen 的目的，就是让它成为我们一直渴望拥有的工具。

为什么叫 Oxen？

“Oxen” 🐂 这个名字来源于这样一个事实：该工具将像优秀的农民照料田地一样，耕耘、维护和版本化您的数据 🌾。让 Oxen 来承担您基础设施中的繁重工作，这样您就可以专注于对您的产品至关重要的更高层次的问题。