From 822ac43c8fe148cdf83e310263a6cd0732ab6a1b Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:43:36 +0000 Subject: [PATCH] docs: make Chinese README the default --- README.md | 406 ++++++++++++++++++++---------------------------------- 1 file changed, 152 insertions(+), 254 deletions(-) diff --git a/README.md b/README.md index 2e45afd..8de7a58 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/tracel-ai/burn) · [上游 README](https://github.com/tracel-ai/burn/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +
@@ -13,102 +19,86 @@ --- -**Burn is both a tensor library and a deep learning framework, optimized for
numerical -computing, training and inference.** +**Burn 既是张量库，也是深度学习框架，针对
数值计算、训练与推理进行了优化。**
-Training and inference usually live in separate worlds. Models are typically trained in Python then -exported to an open format like ONNX or optimized for production engines like vLLM, ONNX Runtime, or -TensorRT. This export step is often brittle and lossy, ruling out complex architectures and advanced -deployment use cases. +训练与推理通常分属两个世界。模型一般在 Python 中训练，再导出为 ONNX 等开放格式，或针对 vLLM、ONNX Runtime、TensorRT 等生产引擎进行优化。这一导出步骤往往脆弱且会有信息损失，从而排除复杂架构与高级部署场景。 -Burn unifies the two. By executing multi-platform tensor operations via a single, unified API, the -exact code used for training is the exact code that runs in production. This makes workloads like -on-device personalization and federated learning straightforward, while enabling teams to go from -prototype to deployment in a single codebase. +Burn 将二者统一起来。通过单一统一 API 执行跨平台张量运算，用于训练的代码与生产环境运行的代码完全一致。这使得端侧个性化、联邦学习（federated learning）等工作负载变得简单，同时让团队能在同一代码库中从原型走向部署。 -Burn preserves the intuitive ergonomics of PyTorch, with dynamic shapes and graphs, but JIT-compiles -streams of tensor operations, performing automatic kernel fusion. You get the flexibility of dynamic -graphs without the performance drop. +Burn 保留了 PyTorch 直观易用的体验，支持动态形状与计算图，但会对张量运算流进行 JIT 编译，并自动进行内核融合（kernel fusion）。你既能获得动态图的灵活性，又不必承受性能下降。 -## Rust for Research? +## Rust 适合科研吗？ -Rust used to be a tough sell for research: long compilation times disrupted the fast -edit-compile-run loop that draws researchers to Python. Burn changes this paradigm. Designed around -incremental compilation, modifying model code recompiles in under 5 seconds, even in release mode. -This delivers a Python-like feedback loop with the speed and safety of Rust. +Rust 过去在科研领域并不讨喜：漫长的编译时间会打断研究人员青睐 Python 的快速编辑-编译-运行循环。Burn 改变了这一范式。围绕增量编译设计，修改模型代码后即使在 release 模式下也能在 5 秒内完成重编译。这带来了类似 Python 的反馈循环，同时具备 Rust 的速度与安全性。 -## Ecosystem +## 生态系统
-Burn is the core of a growing, fully open-source Rust AI ecosystem. You are not adopting a single -library, you are joining a stack that spans GPU compute, model interop and domain toolkits, with -plenty of room to help shape what comes next. +Burn 是一个不断成长的、完全开源的 Rust AI 生态系统的核心。你采用的不只是单一库，而是加入涵盖 GPU 计算、模型互操作与领域工具包的整套技术栈，并有充足空间参与塑造下一步发展方向。
| Category | Project | Description | | ------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Compute | [CubeCL](https://github.com/tracel-ai/cubecl) | GPU compute language and compiler behind Burn's accelerated backends. Write kernels once in Rust, run on CUDA, ROCm, Metal, Vulkan and WebGPU. Usable standalone. | -| Model interop | [burn-onnx](https://github.com/tracel-ai/burn-onnx) | Import ONNX models into Burn as native Rust code | -| | `burn-store` | Save, load and import model weights, including PyTorch and Safetensors | -| Domains | `burn-vision` | Computer vision operators and building blocks | -| | `burn-rl` | Reinforcement learning building blocks | -| | `burn-dataset` | Dataset loading, transforms and ready-made sources | -| Models | [models](https://github.com/tracel-ai/models) | Curated pre-trained models and examples built with Burn | -| Tooling | [burn-bench](https://github.com/tracel-ai/burn-bench) | Benchmark and compare backends, tracking performance over time | +| Compute | [CubeCL](https://github.com/tracel-ai/cubecl) | Burn 加速后端背后的 GPU 计算语言与编译器。用 Rust 编写内核一次，即可在 CUDA、ROCm、Metal、Vulkan 和 WebGPU 上运行。可独立使用。 | +| Model interop | [burn-onnx](https://github.com/tracel-ai/burn-onnx) | 将 ONNX 模型导入 Burn，生成为原生 Rust 代码 | +| | `burn-store` | 保存、加载并导入模型权重，包括 PyTorch 与 Safetensors | +| Domains | `burn-vision` | 计算机视觉算子与构建模块 | +| | `burn-rl` | 强化学习构建模块 | +| | `burn-dataset` | 数据集加载、变换与开箱即用的数据源 | +| Models | [models](https://github.com/tracel-ai/models) | 基于 Burn 构建的精选预训练模型与示例 | +| Tooling | [burn-bench](https://github.com/tracel-ai/burn-bench) | 对后端进行基准测试与对比，并跟踪性能随时间的变化 | -Burn's [CubeCL](https://github.com/tracel-ai/cubecl) backends (CUDA, ROCm, Metal, Vulkan, WebGPU, -CPU) compose with autodiff, fusion and remote-execution decorators, while external and simpler -backends (LibTorch and pure-Rust CPU/`no_std`) compose with autodiff only. See -[Supported Backends](#supported-backends) below for the full matrix. +Burn 的 [CubeCL](https://github.com/tracel-ai/cubecl) 后端（CUDA、ROCm、Metal、Vulkan、WebGPU、 +CPU）可与 autodiff、fusion 与 remote-execution 装饰器组合；而外部及更简单的 +后端（LibTorch 与纯 Rust CPU/`no_std`）仅与 autodiff 组合。完整矩阵见下方 +[Supported Backends](#supported-backends)。 -Every project here is open-source and actively developed. Want to help build the Rust AI ecosystem? -The [good first issues](https://github.com/tracel-ai/burn/contribute) are a great place to start, -and the [Contributing](#contributing) guide will get you set up. +此处的每个项目均为开源并持续开发。想参与共建 Rust AI 生态？ +[good first issues](https://github.com/tracel-ai/burn/contribute) 是很好的起点， +[Contributing](#contributing) 指南可帮助你完成环境配置。
-Community crates 🌱 +社区 crate 🌱
-These crates are not maintained by Tracel, but they are part of the same Rust AI story. Anything -that helps you load data, build environments, or ship models belongs here. Built something that -fits? Open a PR to add it! +这些 crate 不由 Tracel 维护，但同属 Rust AI 故事的一部分。任何有助于加载数据、构建环境或交付模型的项目都可列入此处。有合适作品？提交 PR 将其加入！ | Category | Crate | Description | | -------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- | -| Data & loading | [polars](https://github.com/pola-rs/polars) | Fast DataFrames for tabular data | -| | [arrow-rs](https://github.com/apache/arrow-rs) | Apache Arrow columnar memory format | -| | [image](https://github.com/image-rs/image) | Image decoding, encoding and processing | -| | [hf-hub](https://github.com/huggingface/hf-hub) | Download models and datasets from the Hugging Face Hub | -| Tokenization & NLP | [tokenizers](https://github.com/huggingface/tokenizers) | Fast, production-ready tokenizers | -| | [rust-bert](https://github.com/guillaume-be/rust-bert) | Ready-to-use NLP pipelines and transformer models | -| Numerical & linear algebra | [ndarray](https://github.com/rust-ndarray/ndarray) | N-dimensional arrays | -| | [nalgebra](https://github.com/dimforge/nalgebra) | Linear algebra | -| Classical ML | [linfa](https://github.com/rust-ml/linfa) | Classical ML toolkit, in the spirit of scikit-learn | -| | [smartcore](https://github.com/smartcorelib/smartcore) | Classical ML algorithms, no BLAS/LAPACK required | -| Inference & runtimes | [candle](https://github.com/huggingface/candle) | Minimalist ML framework with a focus on LLM inference | -| | [mistral.rs](https://github.com/EricLBuehler/mistral.rs) | Fast, multimodal LLM inference engine | -| | [ort](https://github.com/pykeio/ort) | ONNX Runtime bindings for hardware-accelerated inference | -| | [tract](https://github.com/sonos/tract) | Pure-Rust inference for ONNX and NNEF models | -| | [wonnx](https://github.com/webonnx/wonnx) | 100% Rust, WebGPU-accelerated ONNX runtime for native and the web | -| LLM apps & RAG | [rig](https://github.com/0xPlaygrounds/rig) | Build modular LLM applications and agents | -| | [langchain-rust](https://github.com/Abraxas-365/langchain-rust) | LangChain-style chain orchestration | -| Embeddings & vector search | [fastembed](https://github.com/Anush008/fastembed-rs) | Generate text embeddings and rerank locally | -| | [qdrant](https://github.com/qdrant/qdrant) | Vector search engine, written in Rust | -| | [lancedb](https://github.com/lancedb/lancedb) | Embedded, developer-friendly vector database | -| Computer vision | [kornia-rs](https://github.com/kornia/kornia-rs) | Low-level 3D computer vision library | -| Simulation & environments | [rapier](https://github.com/dimforge/rapier) | Physics engine for robotics and RL environments | -| Visualization | [rerun](https://github.com/rerun-io/rerun) | Multimodal data and CV/robotics visualization | -| | [plotters](https://github.com/plotters-rs/plotters) | Plotting and charting | +| Data & loading | [polars](https://github.com/pola-rs/polars) | 面向表格数据的快速 DataFrame | +| | [arrow-rs](https://github.com/apache/arrow-rs) | Apache Arrow 列式内存格式 | +| | [image](https://github.com/image-rs/image) | 图像解码、编码与处理 | +| | [hf-hub](https://github.com/huggingface/hf-hub) | 从 Hugging Face Hub 下载模型与数据集 | +| Tokenization & NLP | [tokenizers](https://github.com/huggingface/tokenizers) | 快速、可用于生产的分词器 | +| | [rust-bert](https://github.com/guillaume-be/rust-bert) | 开箱即用的 NLP 流水线与 Transformer 模型 | +| Numerical & linear algebra | [ndarray](https://github.com/rust-ndarray/ndarray) | N 维数组 | +| | [nalgebra](https://github.com/dimforge/nalgebra) | 线性代数 | +| Classical ML | [linfa](https://github.com/rust-ml/linfa) | 经典机器学习工具包，理念类似 scikit-learn | +| | [smartcore](https://github.com/smartcorelib/smartcore) | 经典机器学习算法，无需 BLAS/LAPACK | +| Inference & runtimes | [candle](https://github.com/huggingface/candle) | 极简 ML 框架，侧重 LLM 推理 | +| | [mistral.rs](https://github.com/EricLBuehler/mistral.rs) | 快速、多模态 LLM 推理引擎 | +| | [ort](https://github.com/pykeio/ort) | 面向硬件加速推理的 ONNX Runtime 绑定 | +| | [tract](https://github.com/sonos/tract) | 面向 ONNX 与 NNEF 模型的纯 Rust 推理 | +| | [wonnx](https://github.com/webonnx/wonnx) | 100% Rust、WebGPU 加速的 ONNX 运行时，适用于原生与 Web | +| LLM apps & RAG | [rig](https://github.com/0xPlaygrounds/rig) | 构建模块化 LLM 应用与智能体 | +| | [langchain-rust](https://github.com/Abraxas-365/langchain-rust) | LangChain 风格的链式编排 | +| Embeddings & vector search | [fastembed](https://github.com/Anush008/fastembed-rs) | 在本地生成文本嵌入与重排序 | +| | [qdrant](https://github.com/qdrant/qdrant) | 用 Rust 编写的向量搜索引擎 | +| | [lancedb](https://github.com/lancedb/lancedb) | 嵌入式、对开发者友好的向量数据库 | +| Computer vision | [kornia-rs](https://github.com/kornia/kornia-rs) | 底层 3D 计算机视觉库 | +| Simulation & environments | [rapier](https://github.com/dimforge/rapier) | 面向机器人与 RL 环境的物理引擎 | +| Visualization | [rerun](https://github.com/rerun-io/rerun) | 多模态数据与 CV/机器人可视化 | +| | [plotters](https://github.com/plotters-rs/plotters) | 绘图与图表 |
@@ -117,15 +107,13 @@ fits? Open a PR to add it!
-Burn strives to be as fast as possible on as many hardwares as possible, with robust -implementations. We believe this flexibility is crucial for modern needs where you may train your -models in the cloud, then deploy on customer hardwares, which vary from user to user. +Burn 致力于在尽可能多的硬件上尽可能快地运行，并提供健壮的实现。我们相信，这种灵活性对现代需求至关重要——你或许在云端训练模型，随后在客户的各类硬件上部署，而每台设备的配置都不尽相同。
### Supported Backends -Most backends support all operating systems, so we don't mention them in the tables below. +大多数后端支持所有操作系统，因此我们不在下表中逐一列出。 **GPU Backends:** @@ -149,22 +137,17 @@ Most backends support all operating systems, so we don't mention them in the tab
-Compared to other frameworks, Burn has a very different approach to supporting many backends. By -design, most code is generic over the Backend trait, which allows us to build Burn with swappable -backends. This makes composing backend possible, augmenting them with additional functionalities -such as autodifferentiation and automatic kernel fusion. +与其他框架相比，Burn 在支持多种后端方面采用了截然不同的方法。从设计上讲，大部分代码都针对 Backend trait 泛型化，这使我们能够构建可替换后端的 Burn。这使得组合后端成为可能，并可用自动微分（autodifferentiation）和自动 kernel 融合（automatic kernel fusion）等附加功能对其进行增强。
-Autodiff: Backend decorator that brings backpropagation to any backend 🔄 +Autodiff：为任意后端带来反向传播的 Backend 装饰器 🔄
-Contrary to the aforementioned backends, Autodiff is actually a backend _decorator_. This means that -it cannot exist by itself; it must encapsulate another backend. +与上述后端不同，Autodiff 实际上是一个后端_装饰器_。这意味着它不能独立存在；必须封装另一个后端。 -The simple act of wrapping a base backend with Autodiff transparently equips it with -autodifferentiation support, making it possible to call backward on your model. +只需用 Autodiff 包装一个基础后端，即可透明地为其配备自动微分支持，从而能够对模型调用 backward。 ```rust use burn::backend::{Autodiff, Wgpu}; @@ -188,24 +171,19 @@ fn main() { } ``` -Of note, it is impossible to make the mistake of calling backward on a model that runs on a backend -that does not support autodiff (for inference), as this method is only offered by an Autodiff -backend. +值得注意的是，你不可能在运行于不支持 autodiff（用于推理）的后端上的模型上误调用 backward，因为该方法仅由 Autodiff 后端提供。 -See the [Autodiff Backend README](./crates/burn-autodiff/README.md) for more details. +更多细节请参阅 [Autodiff Backend README](./crates/burn-autodiff/README.md)。
-Fusion: Backend decorator that brings kernel fusion to all first-party backends +Fusion：为所有第一方后端带来 kernel 融合的 Backend 装饰器
-This backend decorator enhances a backend with kernel fusion, provided that the inner backend -supports it. Note that you can compose this backend with other backend decorators such as Autodiff. -All first-party accelerated backends (like WGPU and CUDA) use Fusion by default (`burn/fusion` -feature flag), so you typically don't need to apply it manually. +该后端装饰器可为后端增强 kernel 融合能力，前提是内部后端支持该功能。请注意，你可以将此后端与其他后端装饰器（例如 Autodiff）组合使用。所有第一方加速后端（如 WGPU 和 CUDA）默认使用 Fusion（`burn/fusion` feature flag），因此通常无需手动应用。 ```rust #[cfg(not(feature = "fusion"))] @@ -215,23 +193,19 @@ pub type Cuda = CubeBackend; pub type Cuda = burn_fusion::Fusion>; ``` -Of note, we plan to implement automatic gradient checkpointing based on compute bound and memory -bound operations, which will work gracefully with the fusion backend to make your code run even -faster during training, see [this issue](https://github.com/tracel-ai/burn/issues/936). +值得注意的是，我们计划基于计算密集型（compute bound）和内存密集型（memory bound）操作实现自动梯度检查点（automatic gradient checkpointing），它将能与 fusion 后端良好配合，使训练期间的代码运行得更快；详见 [this issue](https://github.com/tracel-ai/burn/issues/936). -See the [Fusion Backend README](./crates/burn-fusion/README.md) for more details. +更多细节请参阅 [Fusion Backend README](./crates/burn-fusion/README.md)。
-Remote (Beta): Backend decorator for remote backend execution, useful for distributed computations +Remote（Beta）：用于远程后端执行的后端装饰器，适用于分布式计算
-That backend has two parts, one client and one server. The client sends tensor operations over the -network to a remote compute backend. You can use any first-party backend as server in a single line -of code: +该后端包含两部分：一个客户端和一个服务端。客户端通过网络将张量运算发送至远程计算后端。你只需一行代码即可将任意第一方后端用作服务端： ```rust fn main_server() { @@ -261,13 +235,9 @@ fn main_client() {
-The whole deep learning workflow is made easy with Burn, as you can monitor your training progress -with an ergonomic dashboard, and run inference everywhere from embedded devices to large GPU -clusters. +借助 Burn，整个深度学习工作流变得更加轻松：你可以通过符合人体工学的仪表盘监控训练进度，并在从嵌入式设备到大型 GPU 集群的各类环境中运行推理。 -Burn was built from the ground up with training and inference in mind. It's also worth noting how -Burn, in comparison to frameworks like PyTorch, simplifies the transition from training to -deployment, eliminating the need for code changes. +Burn 从设计之初就兼顾训练与推理。同样值得一提的是，与 PyTorch 等框架相比，Burn 简化了从训练到部署的过渡，无需修改代码。
@@ -282,7 +252,7 @@ deployment, eliminating the need for code changes.
-**Click on the following sections to expand 👇** +**点击以下章节展开 👇**
@@ -290,14 +260,9 @@ Training Dashboard 📈
-As you can see in the previous video (click on the picture!), a new terminal UI dashboard based on -the [Ratatui](https://github.com/ratatui-org/ratatui) crate allows users to follow their training -with ease without having to connect to any external application. +如你在上一段视频中（点击图片！）所见，基于 [Ratatui](https://github.com/ratatui-org/ratatui) crate 的全新终端 UI 仪表盘让用户无需连接任何外部应用，即可轻松跟踪训练过程。 -You can visualize your training and validation metrics updating in real-time and analyze the -lifelong progression or recent history of any registered metrics using only the arrow keys. Break -from the training loop without crashing, allowing potential checkpoints to be fully written or -important pieces of code to complete without interruption 🛡 +你可以实时查看训练与验证指标的更新，并仅使用方向键分析任意已注册指标的长期走势或近期历史。可在不导致崩溃的情况下跳出训练循环，从而让潜在的检查点完整写入，或让重要代码片段不受干扰地完成 🛡
@@ -307,17 +272,11 @@ ONNX Support 🐫
-Burn supports importing ONNX (Open Neural Network Exchange) models through the -[burn-onnx](https://github.com/tracel-ai/burn-onnx) crate, allowing you to easily port models from -TensorFlow or PyTorch to Burn. The ONNX model is converted into Rust code that uses Burn's native -APIs, enabling the imported model to run on any Burn backend (CPU, GPU, WebAssembly) and benefit -from all of Burn's optimizations like automatic kernel fusion. +Burn 支持通过 [burn-onnx](https://github.com/tracel-ai/burn-onnx) crate 导入 ONNX（Open Neural Network Exchange）模型，让你能够轻松将 TensorFlow 或 PyTorch 模型迁移到 Burn。ONNX 模型会被转换为使用 Burn 原生 API 的 Rust 代码，使导入的模型可在任意 Burn 后端（CPU、GPU、WebAssembly）上运行，并受益于 Burn 的全部优化，例如自动 kernel 融合。 -Our ONNX support is further described in -[this section of the Burn Book 🔥](https://burn.dev/books/burn/onnx-import.html). +我们的 ONNX 支持在 Burn Book 的 [this section of the Burn Book 🔥](https://burn.dev/books/burn/onnx-import.html). 中有进一步说明。 -> **Note**: This crate is in active development and currently supports a -> [limited set of ONNX operators](https://github.com/tracel-ai/burn-onnx/blob/main/SUPPORTED-ONNX-OPS.md). +> **Note**: 该 crate 正在积极开发中，目前仅支持 [limited set of ONNX operators](https://github.com/tracel-ai/burn-onnx/blob/main/SUPPORTED-ONNX-OPS.md).
@@ -327,12 +286,9 @@ Importing PyTorch or Safetensors Models 🚚
-You can load weights from PyTorch or Safetensors formats directly into your Burn-defined models. -This makes it easy to reuse existing models while benefiting from Burn's performance and deployment -features. +你可以将 PyTorch 或 Safetensors 格式的权重直接加载到 Burn 定义的模型中。这样既能复用现有模型，又能享受 Burn 的性能与部署特性。 -Learn more in the [Saving & Loading Models](https://burn.dev/books/burn/saving-and-loading.html) -section of the Burn Book. +更多信息请参阅 Burn Book 的 [Saving & Loading Models](https://burn.dev/books/burn/saving-and-loading.html) 章节。 @@ -342,58 +298,47 @@ Inference in the Browser 🌐
-Several of our backends can run in WebAssembly environments: Flex for CPU execution, and WGPU for -GPU acceleration via WebGPU. This means that you can run inference directly within a browser. We -provide several examples of this: +我们的多个后端可在 WebAssembly 环境中运行：Flex 用于 CPU 执行，WGPU 通过 WebGPU 提供 GPU 加速。这意味着你可以直接在浏览器内运行推理。我们提供了多个相关示例： -- [MNIST](./examples/mnist-inference-web) where you can draw digits and a small convnet tries to - find which one it is! 2️⃣ 7️⃣ 😰 -- [Image Classification](https://github.com/tracel-ai/burn-onnx/tree/main/examples/image-classification-web) - where you can upload images and classify them! 🌄 +- [MNIST](./examples/mnist-inference-web)：你可以手绘数字，由一个小型卷积神经网络尝试识别是哪一个！2️⃣ 7️⃣ 😰 +- [图像分类](https://github.com/tracel-ai/burn-onnx/tree/main/examples/image-classification-web)：上传图像并进行分类！🌄
-Embedded: no_std support ⚙️ +嵌入式：no_std 支持 ⚙️
-Burn's core components support [no_std](https://docs.rust-embedded.org/book/intro/no-std.html). This -means it can run in bare metal environment such as embedded devices without an operating system. +Burn 的核心组件支持 [no_std](https://docs.rust-embedded.org/book/intro/no-std.html).。这意味着它可以在裸机（bare metal）环境（例如没有操作系统的嵌入式设备）中运行。 -> As of now, only the Flex backend can be used in a _no_std_ environment. +> 截至目前，只有 Flex 后端可以在 _no_std_ 环境中使用。

-### Benchmarks +### 基准测试 -To evaluate performance across different backends and track improvements over time, we provide a -dedicated benchmarking suite. +为了评估不同后端的性能并跟踪随时间的改进，我们提供了专用的基准测试套件。 -Run and compare benchmarks using [burn-bench](https://github.com/tracel-ai/burn-bench). +使用 [burn-bench](https://github.com/tracel-ai/burn-bench). 运行并比较基准测试 -> ⚠️ **Warning** When using one of the `wgpu` backends, you may encounter compilation errors related -> to recursive type evaluation. This is due to complex type nesting within the `wgpu` dependency -> chain. To resolve this issue, add the following line at the top of your `main.rs` or `lib.rs` -> file: +> ⚠️ **警告** 使用 `wgpu` 后端之一时，你可能会遇到与递归类型求值相关的编译错误。这是由于 `wgpu` 依赖链中存在复杂的类型嵌套。要解决此问题，请在 `main.rs` 或 `lib.rs` 文件顶部添加以下行： > > ```rust > #![recursion_limit = "256"] > ``` > -> The default recursion limit (128) is often just below the required depth (typically 130-150) due -> to deeply nested associated types and trait bounds. +> 由于深度嵌套的关联类型（associated types）和 trait 约束，默认递归限制（128）通常刚好低于所需深度（通常为 130-150）。 -## Getting Started +## 入门指南
-Just heard of Burn? You are at the right place! Just continue reading this section and we hope you -can get on board really quickly. +刚听说 Burn？你来对地方了！继续阅读本节，我们希望你能很快上手。
@@ -403,26 +348,19 @@ The Burn Book 🔥
-To begin working effectively with Burn, it is crucial to understand its key components and -philosophy. This is why we highly recommend new users to read the first sections of -[The Burn Book 🔥](https://burn.dev/books/burn/). It provides detailed examples and explanations -covering every facet of the framework, including building blocks like tensors, modules, and -optimizers, all the way to advanced usage, like coding your own GPU kernels. +要高效使用 Burn，理解其核心组件与设计理念至关重要。因此我们强烈建议新用户阅读 [The Burn Book 🔥](https://burn.dev/books/burn/). 的前几节。书中提供详细示例与说明，涵盖框架的方方面面，从张量（tensors）、模块（modules）、优化器（optimizers）等构建块，到进阶用法（例如编写自己的 GPU 内核）。 -> The project is constantly evolving, and we try as much as possible to keep the book up to date -> with new additions. However, we might miss some details sometimes, so if you see something weird, -> let us know! We also gladly accept Pull Requests 😄 +> 项目仍在持续演进，我们会尽可能让书籍与新增内容保持同步。但有时可能遗漏一些细节，若发现异常请告诉我们！我们也欢迎 Pull Request 😄
-Examples 🙏 +示例 🙏
-Let's start with a code snippet that shows how intuitive the framework is to use! In the following, -we declare a neural network module with some parameters along with its forward pass. +先看一段代码片段，感受框架使用的直观性！下面，我们声明一个带若干参数的神经网络模块及其前向传播（forward pass）。 ```rust use burn::nn; @@ -448,135 +386,95 @@ impl PositionWiseFeedForward { } ``` -We have a somewhat large amount of [examples](./examples) in the repository that shows how to use -the framework in different scenarios. +仓库中有相当数量的 [示例](./examples)，展示如何在不同场景下使用该框架。 -Following [the book](https://burn.dev/books/burn/): +按照 [书籍](https://burn.dev/books/burn/): -- [Basic Workflow](./examples/guide) : Creates a custom CNN `Module` to train on the MNIST dataset - and use for inference. -- [Custom Training Loop](./examples/custom-training-loop) : Implements a basic training loop instead - of using the `Learner`. -- [Custom WGPU Kernel](./examples/custom-wgpu-kernel) : Learn how to create your own custom - operation with the WGPU backend. +- [Basic Workflow](./examples/guide) ：创建自定义 CNN `Module`，在 MNIST 数据集上训练并用于推理。 +- [Custom Training Loop](./examples/custom-training-loop) ：实现基础训练循环，而非使用 `Learner`。 +- [Custom WGPU Kernel](./examples/custom-wgpu-kernel) ：学习如何使用 WGPU 后端创建自己的自定义算子。 -Additional examples: +更多示例： -- [Custom CSV Dataset](./examples/custom-csv-dataset) : Implements a dataset to parse CSV data for a - regression task. -- [Regression](./examples/simple-regression) : Trains a simple MLP on the California Housing dataset - to predict the median house value for a district. -- [Custom Image Dataset](./examples/custom-image-dataset) : Trains a simple CNN on custom image - dataset following a simple folder structure. -- [Custom Renderer](./examples/custom-renderer) : Implements a custom renderer to display the - [`Learner`](./building-blocks/learner.md) progress. -- [Image Classification Web](./examples/image-classification-web) : Image classification web browser - demo using Burn, WGPU and WebAssembly. -- [MNIST Inference on Web](./examples/mnist-inference-web) : An interactive MNIST inference demo in - the browser. The demo is available [online](https://burn.dev/demo/). -- [MNIST Training](./examples/mnist) : Demonstrates how to train a custom `Module` (MLP) with the - `Learner` configured to log metrics and keep training checkpoints. -- [PyTorch Import Inference](./examples/import-model-weights) : Imports a PyTorch model pre-trained - on MNIST to perform inference on a sample image with Burn. -- [Text Classification](./examples/text-classification) : Trains a text classification transformer - model on the AG News or DbPedia dataset. The trained model can then be used to classify a text - sample. -- [Text Generation](./examples/text-generation) : Trains a text generation transformer model on the - DbPedia dataset. -- [Wasserstein GAN MNIST](./examples/wgan) : Trains a WGAN model to generate new handwritten digits - based on MNIST. +- [Custom CSV Dataset](./examples/custom-csv-dataset) ：实现用于解析 CSV 数据的数据集，以完成回归任务。 +- [Regression](./examples/simple-regression) ：在 California Housing 数据集上训练简单 MLP，预测各街区房屋价格中位数。 +- [Custom Image Dataset](./examples/custom-image-dataset) ：按简单文件夹结构，在自定义图像数据集上训练简单 CNN。 +- [Custom Renderer](./examples/custom-renderer) ：实现自定义渲染器以显示 [`Learner`](./building-blocks/learner.md) 进度。 +- [Image Classification Web](./examples/image-classification-web) ：使用 Burn、WGPU 与 WebAssembly 的图像分类浏览器演示。 +- [MNIST Inference on Web](./examples/mnist-inference-web) ：浏览器中的交互式 MNIST 推理演示。该演示可 [在线](https://burn.dev/demo/). 体验 +- [MNIST Training](./examples/mnist) ：演示如何训练自定义 `Module`（MLP），并配置 `Learner` 以记录指标并保存训练检查点。 +- [PyTorch Import Inference](./examples/import-model-weights) ：导入在 MNIST 上预训练的 PyTorch 模型，使用 Burn 对样本图像进行推理。 +- [Text Classification](./examples/text-classification) ：在 AG News 或 DbPedia 数据集上训练文本分类 Transformer 模型。训练后的模型可用于对文本样本进行分类。 +- [Text Generation](./examples/text-generation) ：在 DbPedia 数据集上训练文本生成 Transformer 模型。 +- [Wasserstein GAN MNIST](./examples/wgan) ：训练 WGAN 模型，基于 MNIST 生成新的手写数字。 -For more practical insights, you can clone the repository and run any of them directly on your -computer! +若想获得更实用的体验，可克隆仓库并在你的计算机上直接运行其中任意示例！
-Pre-trained Models 🤖 +预训练模型 🤖
-We keep an updated and curated list of models and examples built with Burn, see the -[tracel-ai/models repository](https://github.com/tracel-ai/models) for more details. +我们维护一份持续更新、精选的 Burn 构建模型与示例列表，详见 [tracel-ai/models 仓库](https://github.com/tracel-ai/models)。 -Don't see the model you want? Don't hesitate to open an issue, and we may prioritize it. Built a -model using Burn and want to share it? You can also open a Pull Request and add your model under the -community section! +找不到想要的模型？欢迎提交 issue，我们可能会优先安排。你用 Burn 构建了模型并想分享？也可以提交 Pull Request，将模型添加到社区栏目！
-Why use Rust for AI? 🦀 +为何用 Rust 做 AI？🦀
-Deep Learning is a special form of software where you need very high level abstractions as well as -extremely fast execution time. Rust is the perfect candidate for that use case since it provides -zero-cost abstractions to easily create neural network modules, and fine-grained control over memory -to optimize every detail. To this day, the mainstream solution has been to offer APIs in Python but -rely on bindings to low-level languages such as C/C++. This reduces portability, increases -complexity and creates friction between researchers and engineers. Rust's approach to abstractions -is versatile enough to tackle this two-language dichotomy, and Cargo makes it easy to build, test -and deploy from any environment, which is usually a pain in Python. +深度学习是一种特殊的软件形态：既需要高层抽象，又需要极快的执行速度。Rust 正是这一场景的理想选择——它提供零成本抽象，便于构建神经网络模块，并对内存进行细粒度控制以优化每一个细节。至今，主流方案仍以 Python 提供 API，却依赖对 C/C++ 等底层语言的绑定。这会降低可移植性、增加复杂度，并在研究人员与工程师之间制造摩擦。Rust 的抽象方式足够灵活，可应对这种「双语言」割裂；而 Cargo 让在任何环境中构建、测试与部署都变得简单——这在 Python 中往往是痛点。 -Rust's AI ecosystem is young, but it is real and growing quickly. Foundational pieces are already -here: Burn and [CubeCL](https://github.com/tracel-ai/cubecl) for training and compute, -[candle](https://github.com/huggingface/candle) for inference, Hugging Face's `tokenizers` and -`safetensors`, and `polars` and `ndarray` for data. Betting on Rust today means betting on a stack -that is growing, and one where contributors still shape the direction. The pieces that don't exist -yet are opportunities rather than dead-ends (see [Contributing](#contributing)). +Rust 的 AI 生态仍年轻，但真实存在且增长迅速。基础组件已就位：Burn 与 [CubeCL](https://github.com/tracel-ai/cubecl) 用于训练与计算，[candle](https://github.com/huggingface/candle) 用于推理，Hugging Face 的 `tokenizers` 与 `safetensors`，以及 `polars` 与 `ndarray` 用于数据。今天押注 Rust，意味着押注一个仍在成长、贡献者仍能塑造方向的技术栈。尚未存在的组件是机遇而非死胡同（参见 [贡献](#contributing)）。 -Rust is also what makes one-stack-everywhere possible: a single self-contained binary with no Python -runtime to ship, running from servers down to `no_std` embedded targets. +Rust 还让「一套技术栈，处处可用」成为可能：无需附带 Python 运行时，只需一个自包含二进制文件，即可从服务器运行到 `no_std` 嵌入式目标。

-> **Deprecation Note**
Since `0.14.0`, the internal structure for tensor data has changed. The -> previous `Data` struct was deprecated and officially removed since `0.17.0` in favor of the new -> `TensorData` struct, which allows for more flexibility by storing the underlying data as bytes and -> keeping the data type as a field. If you are using `Data` in your code, make sure to switch to -> `TensorData`. +> **弃用说明**
自 `0.14.0` 起，张量数据的内部结构已变更。原先的 `Data` 结构体已被弃用，并自 `0.17.0` 起正式移除，改用新的 `TensorData` 结构体；后者将底层数据以字节形式存储，并将数据类型作为字段保存，从而更灵活。若代码中仍在使用 `Data`，请务必迁移至 `TensorData`。 +> 如果你正在尝试加载在先前版本中保存的模型记录（model record），请确保使用 burn 的旧版本（<=0.16.0）启用 `record-backward-compat` 功能。否则， +> 该记录将无法被正确反序列化（deserialize），你会收到一条错误消息（该消息也会指向 +> 向后兼容的功能标志）。向后兼容性在反序列化（加载）方面得到了维护，因此一旦你重新保存该记录， +> 它将按新结构保存，你就能升级到此版本。请注意，二进制格式（binary formats）不向后兼容。因此，你需要在旧版本中加载记录， +> 并将其保存为其他自描述记录格式（self-describing record formats）之一，然后再使用兼容版本（如前所述）并启用 +> `record-backward-compat` 功能标志。 -->
-Loading Model Records From Previous Versions ⚠️ +从先前版本加载模型记录 ⚠️
-In the event that you are trying to load a model record saved in a version older than `0.14.0`, make -sure to use a compatible version (`0.14`, `0.15` or `0.16`) with the `record-backward-compat` -feature flag. +如果你正在尝试加载在早于 `0.14.0` 的版本中保存的模型记录，请 +确保使用兼容版本（`0.14`、`0.15` 或 `0.16`），并启用 `record-backward-compat` +功能标志。 ``` features = [..., "record-backward-compat"] ``` -Otherwise, the record won't be deserialized correctly and you will get an error message. This error -will also point you to the backward compatible feature flag. +否则，该记录将无法被正确反序列化，你会收到一条错误消息。该错误 +消息也会指向向后兼容的功能标志。 -The backward compatibility was maintained for deserialization when loading records. Therefore, as -soon as you have saved the record again it will be saved according to the new structure and you can -upgrade back to the current version +在加载记录时，反序列化方面保持了向后兼容性。因此， +一旦你重新保存该记录，它将按新结构保存，你就可以 +升级回当前版本 -Please note that binary formats are not backward compatible. Thus, you will need to load your record -in a previous version and save it in any of the other self-describing record format (e.g., using the -`NamedMpkFileRecorder`) before using a compatible version (as described) with the -`record-backward-compat` feature flag. +请注意，二进制格式不向后兼容。因此，你需要在旧版本中加载记录， +并将其保存为其他任一自描述记录格式（例如，使用 +`NamedMpkFileRecorder`），然后再使用兼容版本（如前所述）并启用 +`record-backward-compat` 功能标志。
@@ -585,9 +483,9 @@ in a previous version and save it in any of the other self-describing record for
-If you are excited about the project, don't hesitate to join our -[Discord](https://discord.gg/uPEBbYYDB6)! We try to be as welcoming as possible to everybody from -any background. You can ask your questions and share what you built with the community! +如果你对这个项目感兴趣，欢迎加入我们的 +[Discord](https://discord.gg/uPEBbYYDB6)! 我们尽力欢迎来自 +任何背景的人。你可以向社区提问，并分享你的成果！
@@ -595,19 +493,19 @@ any background. You can ask your questions and share what you built with the com ### Contributing -Before contributing, please read the [Contributing Guidelines](./CONTRIBUTING.md) and our -[Code of Conduct](./CODE-OF-CONDUCT.md). The [Contributor Book](https://burn.dev/contributor-book/) -covers architecture, environment setup, and guides for common tasks. +在贡献代码之前，请阅读 [Contributing Guidelines](./CONTRIBUTING.md) 和我们的 +[Code of Conduct](./CODE-OF-CONDUCT.md)。[Contributor Book](https://burn.dev/contributor-book/) +涵盖架构、环境搭建以及常见任务的指南。 ## Status -Burn is currently in active development, and there will be breaking changes. While any resulting -issues are likely to be easy to fix, there are no guarantees at this stage. +Burn 目前处于积极开发中，可能会有破坏性变更（breaking changes）。虽然由此产生的问题 +通常较容易修复，但现阶段无法提供任何保证。 ## License -Burn is distributed under the terms of both the MIT license and the Apache License (Version 2.0). -See [LICENSE-APACHE](./LICENSE-APACHE) and [LICENSE-MIT](./LICENSE-MIT) for details. Opening a pull -request is assumed to signal agreement with these licensing terms. +Burn 根据 MIT 许可证和 Apache License（Version 2.0）的条款进行分发。 +详见 [LICENSE-APACHE](./LICENSE-APACHE) 和 [LICENSE-MIT](./LICENSE-MIT)。提交 pull +request 即视为同意这些许可条款。