[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-LaurentMazare--tch-rs":3,"tool-LaurentMazare--tch-rs":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",157379,2,"2026-04-15T23:32:42",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":78,"owner_email":77,"owner_twitter":79,"owner_website":80,"owner_url":81,"languages":82,"stars":113,"forks":114,"last_commit_at":115,"license":116,"difficulty_score":117,"env_os":118,"env_gpu":119,"env_ram":120,"env_deps":121,"category_tags":127,"github_topics":128,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":134,"updated_at":135,"faqs":136,"releases":166},7974,"LaurentMazare\u002Ftch-rs","tch-rs","Rust bindings for the C++ api of PyTorch.","tch-rs 是连接 Rust 编程语言与 PyTorch 深度学习框架的桥梁。它通过封装 PyTorch 的 C++ 接口（libtorch），让开发者能够直接在 Rust 项目中调用强大的 PyTorch 功能，如张量运算、神经网络构建及模型训练。\n\n这一工具主要解决了 Rust 生态中缺乏原生、高性能深度学习支持的痛点。以往开发者若想在 Rust 中使用 PyTorch，往往需要复杂的跨语言调用或牺牲性能，而 tch-rs 提供了近乎零开销的绑定，既保留了 PyTorch 完整的 API 能力，又发挥了 Rust 在内存安全和并发处理上的优势。\n\ntch-rs 特别适合系统程序员、AI 工程师及研究人员使用，尤其是那些希望将深度学习模型部署到对性能和稳定性要求极高的生产环境，或致力于开发高性能 AI 基础设施的团队。\n\n其技术亮点在于设计理念的“原汁原味”：它尽可能贴近 PyTorch 原始的 C++ API 行为，确保功能同步更新，同时为未来构建更符合 Rust 习惯的高级封装打下坚实基础。此外，它支持灵活的 libtorch 集成方式，包括自动下载预编译二进制文件、复用现有 ","tch-rs 是连接 Rust 编程语言与 PyTorch 深度学习框架的桥梁。它通过封装 PyTorch 的 C++ 接口（libtorch），让开发者能够直接在 Rust 项目中调用强大的 PyTorch 功能，如张量运算、神经网络构建及模型训练。\n\n这一工具主要解决了 Rust 生态中缺乏原生、高性能深度学习支持的痛点。以往开发者若想在 Rust 中使用 PyTorch，往往需要复杂的跨语言调用或牺牲性能，而 tch-rs 提供了近乎零开销的绑定，既保留了 PyTorch 完整的 API 能力，又发挥了 Rust 在内存安全和并发处理上的优势。\n\ntch-rs 特别适合系统程序员、AI 工程师及研究人员使用，尤其是那些希望将深度学习模型部署到对性能和稳定性要求极高的生产环境，或致力于开发高性能 AI 基础设施的团队。\n\n其技术亮点在于设计理念的“原汁原味”：它尽可能贴近 PyTorch 原始的 C++ API 行为，确保功能同步更新，同时为未来构建更符合 Rust 习惯的高级封装打下坚实基础。此外，它支持灵活的 libtorch 集成方式，包括自动下载预编译二进制文件、复用现有 Python 环境或直接链接系统库，并针对 Windows 平台提供了详细的兼容性指引，大大降低了配置门槛。","# tch-rs\nRust bindings for the C++ api of PyTorch. The goal of the `tch` crate is to\nprovide some thin wrappers around the C++ PyTorch api (a.k.a. libtorch). It\naims at staying as close as possible to the original C++ api. More idiomatic\nrust bindings could then be developed on top of this. The\n[documentation](https:\u002F\u002Fdocs.rs\u002Ftch\u002F) can be found on docs.rs.\n\n[![Build Status](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fworkflows\u002FContinuous%20integration\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Factions)\n[![Latest version](https:\u002F\u002Fimg.shields.io\u002Fcrates\u002Fv\u002Ftch.svg)](https:\u002F\u002Fcrates.io\u002Fcrates\u002Ftch)\n[![Documentation](https:\u002F\u002Fdocs.rs\u002Ftch\u002Fbadge.svg)](https:\u002F\u002Fdocs.rs\u002Ftch)\n[![Dependency Status](https:\u002F\u002Fdeps.rs\u002Frepo\u002Fgithub\u002FLaurentMazare\u002Ftch-rs\u002Fstatus.svg)](https:\u002F\u002Fdeps.rs\u002Frepo\u002Fgithub\u002FLaurentMazare\u002Ftch-rs)\n![License](https:\u002F\u002Fimg.shields.io\u002Fcrates\u002Fl\u002Ftch.svg)\n[changelog](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmain\u002FCHANGELOG.md)\n\n\nThe code generation part for the C api on top of libtorch comes from\n[ocaml-torch](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Focaml-torch).\n\n## Getting Started\n\nThis crate requires the C++ PyTorch library (libtorch) in version *v2.11.0* to be available on\nyour system. You can either:\n\n- Use the system-wide libtorch installation (default).\n- Install libtorch manually and let the build script know about it via the `LIBTORCH` environment variable.\n- Use a Python PyTorch install, to do this set `LIBTORCH_USE_PYTORCH=1`.\n- When a system-wide libtorch can't be found and `LIBTORCH` is not set, the\n  build script can download a pre-built binary version of libtorch by using\n  the `download-libtorch` feature. By default a CPU version is used. The\n  `TORCH_CUDA_VERSION` environment variable can be set to `cu117` in order to\n  get a pre-built binary using CUDA 11.7.\n\n### System-wide Libtorch\n\nOn linux platforms, the build script will look for a system-wide libtorch\nlibrary in `\u002Fusr\u002Flib\u002Flibtorch.so`.\n\n### Python PyTorch Install\n\nIf the `LIBTORCH_USE_PYTORCH` environment variable is set, the active python\ninterpreter is called to retrieve information about the torch python package.\nThis version is then linked against.\n\n### Libtorch Manual Install\n\n- Get `libtorch` from the\n[PyTorch website download section](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F) and extract\nthe content of the zip file.\n- For Linux and macOS users, add the following to your `.bashrc` or equivalent, where `\u002Fpath\u002Fto\u002Flibtorch`\nis the path to the directory that was created when unzipping the file.\n```bash\nexport LIBTORCH=\u002Fpath\u002Fto\u002Flibtorch\n```\nThe header files location can also be specified separately from the shared library via\nthe following:\n```bash\n# LIBTORCH_INCLUDE must contain `include` directory.\nexport LIBTORCH_INCLUDE=\u002Fpath\u002Fto\u002Flibtorch\u002F\n# LIBTORCH_LIB must contain `lib` directory.\nexport LIBTORCH_LIB=\u002Fpath\u002Fto\u002Flibtorch\u002F\n```\n- For Windows users, assuming that `X:\\path\\to\\libtorch` is the unzipped libtorch directory.\n    - Navigate to Control Panel -> View advanced system settings -> Environment variables.\n    - Create the `LIBTORCH` variable and set it to `X:\\path\\to\\libtorch`.\n    - Append `X:\\path\\to\\libtorch\\lib` to the `Path` variable.\n\n  If you prefer to temporarily set environment variables, in PowerShell you can run\n```powershell\n$Env:LIBTORCH = \"X:\\path\\to\\libtorch\"\n$Env:Path += \";X:\\path\\to\\libtorch\\lib\"\n```\n- You should now be able to run some examples, e.g. `cargo run --example basics`.\n\n### Windows Specific Notes\n\nAs per [the pytorch docs](https:\u002F\u002Fpytorch.org\u002Fcppdocs\u002Finstalling.html) the Windows debug and release builds are not ABI-compatible. This could lead to some segfaults if the incorrect version of libtorch is used.\n\nIt is recommended to use the MSVC Rust toolchain (e.g. by installing `stable-x86_64-pc-windows-msvc` via rustup) rather than a MinGW based one as PyTorch has compatibilities issues with MinGW.\n\n### Static Linking\n\nWhen setting environment variable `LIBTORCH_STATIC=1`, `libtorch` is statically\nlinked rather than using the dynamic libraries. The pre-compiled artifacts don't\nseem to include `libtorch.a` by default so this would have to be compiled\nmanually, e.g. via the following:\n\n```bash\ngit clone -b v2.11.0 --recurse-submodule https:\u002F\u002Fgithub.com\u002Fpytorch\u002Fpytorch.git pytorch-static --depth 1\ncd pytorch-static\nUSE_CUDA=OFF BUILD_SHARED_LIBS=OFF python setup.py build\n# export LIBTORCH to point at the build directory in pytorch-static.\n```\n\n## Examples\n\n### Basic Tensor Operations\n\nThis crate provides a tensor type which wraps PyTorch tensors. Here is a minimal\nexample of how to perform some tensor operations.\n\n```rust\nuse tch::Tensor;\n\nfn main() {\n    let t = Tensor::from_slice(&[3, 1, 4, 1, 5]);\n    let t = t * 2;\n    t.print();\n}\n```\n\n### Training a Model via Gradient Descent\n\nPyTorch provides automatic differentiation for most tensor operations\nit supports. This is commonly used to train models using gradient\ndescent. The optimization is performed over variables which are created\nvia a `nn::VarStore` by defining their shapes and initializations.\n\nIn the example below `my_module` uses two variables `x1` and `x2`\nwhich initial values are 0. The forward pass applied to tensor `xs`\nreturns `xs * x1 + exp(xs) * x2`.\n\nOnce the model has been generated, a `nn::Sgd` optimizer is created.\nThen on each step of the training loop:\n\n- The forward pass is applied to a mini-batch of data.\n- A loss is computed as the mean square error between the model output and the mini-batch ground truth.\n- Finally an optimization step is performed: gradients are computed and variables from the `VarStore` are modified accordingly.\n\n\n```rust\nuse tch::nn::{Module, OptimizerConfig};\nuse tch::{kind, nn, Device, Tensor};\n\nfn my_module(p: nn::Path, dim: i64) -> impl nn::Module {\n    let x1 = p.zeros(\"x1\", &[dim]);\n    let x2 = p.zeros(\"x2\", &[dim]);\n    nn::func(move |xs| xs * &x1 + xs.exp() * &x2)\n}\n\nfn gradient_descent() {\n    let vs = nn::VarStore::new(Device::Cpu);\n    let my_module = my_module(vs.root(), 7);\n    let mut opt = nn::Sgd::default().build(&vs, 1e-2).unwrap();\n    for _idx in 1..50 {\n        \u002F\u002F Dummy mini-batches made of zeros.\n        let xs = Tensor::zeros(&[7], kind::FLOAT_CPU);\n        let ys = Tensor::zeros(&[7], kind::FLOAT_CPU);\n        let loss = (my_module.forward(&xs) - ys).pow_tensor_scalar(2).sum(kind::Kind::Float);\n        opt.backward_step(&loss);\n    }\n}\n```\n\n### Writing a Simple Neural Network\n\nThe `nn` api can be used to create neural network architectures, e.g. the following code defines\na simple model with one hidden layer and trains it on the MNIST dataset using the Adam optimizer.\n\n```rust\nuse anyhow::Result;\nuse tch::{nn, nn::Module, nn::OptimizerConfig, Device};\n\nconst IMAGE_DIM: i64 = 784;\nconst HIDDEN_NODES: i64 = 128;\nconst LABELS: i64 = 10;\n\nfn net(vs: &nn::Path) -> impl Module {\n    nn::seq()\n        .add(nn::linear(\n            vs \u002F \"layer1\",\n            IMAGE_DIM,\n            HIDDEN_NODES,\n            Default::default(),\n        ))\n        .add_fn(|xs| xs.relu())\n        .add(nn::linear(vs, HIDDEN_NODES, LABELS, Default::default()))\n}\n\npub fn run() -> Result\u003C()> {\n    let m = tch::vision::mnist::load_dir(\"data\")?;\n    let vs = nn::VarStore::new(Device::Cpu);\n    let net = net(&vs.root());\n    let mut opt = nn::Adam::default().build(&vs, 1e-3)?;\n    for epoch in 1..200 {\n        let loss = net\n            .forward(&m.train_images)\n            .cross_entropy_for_logits(&m.train_labels);\n        opt.backward_step(&loss);\n        let test_accuracy = net\n            .forward(&m.test_images)\n            .accuracy_for_logits(&m.test_labels);\n        println!(\n            \"epoch: {:4} train loss: {:8.5} test acc: {:5.2}%\",\n            epoch,\n            f64::from(&loss),\n            100. * f64::from(&test_accuracy),\n        );\n    }\n    Ok(())\n}\n```\n\nMore details on the training loop can be found in the\n[detailed tutorial](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fmnist).\n\n### Using some Pre-Trained Model\n\nThe [pretrained-models  example](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fpretrained-models\u002Fmain.rs)\nillustrates how to use some pre-trained computer vision model on an image.\nThe weights - which have been extracted from the PyTorch implementation - can be\ndownloaded here [resnet18.ot](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Freleases\u002Fdownload\u002Fmw\u002Fresnet18.ot)\nand here [resnet34.ot](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Freleases\u002Fdownload\u002Fmw\u002Fresnet34.ot).\n\nThe example can then be run via the following command:\n```bash\ncargo run --example pretrained-models -- resnet18.ot tiger.jpg\n```\nThis should print the top 5 imagenet categories for the image. The code for this example is pretty simple.\n\n```rust\n    \u002F\u002F First the image is loaded and resized to 224x224.\n    let image = imagenet::load_image_and_resize(image_file)?;\n\n    \u002F\u002F A variable store is created to hold the model parameters.\n    let vs = tch::nn::VarStore::new(tch::Device::Cpu);\n\n    \u002F\u002F Then the model is built on this variable store, and the weights are loaded.\n    let resnet18 = tch::vision::resnet::resnet18(vs.root(), imagenet::CLASS_COUNT);\n    vs.load(weight_file)?;\n\n    \u002F\u002F Apply the forward pass of the model to get the logits and convert them\n    \u002F\u002F to probabilities via a softmax.\n    let output = resnet18\n        .forward_t(&image.unsqueeze(0), \u002F*train=*\u002F false)\n        .softmax(-1);\n\n    \u002F\u002F Finally print the top 5 categories and their associated probabilities.\n    for (probability, class) in imagenet::top(&output, 5).iter() {\n        println!(\"{:50} {:5.2}%\", class, 100.0 * probability)\n    }\n```\n### Importing Pre-Trained Weights from PyTorch Using SafeTensors\n\n`safetensors` is a new simple format by HuggingFace for storing tensors. It does not rely on Python's `pickle` module, and therefore the tensors are not bound to the specific classes and the exact directory structure used when the model is saved. It is also zero-copy, which means that reading the file will require no more memory than the original file.\n\nFor more information on `safetensors`, please check out https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsafetensors\n\n#### Installing `safetensors`\n\nYou can install `safetensors` via the pip manager:\n\n```\npip install safetensors\n```\n\n#### Exporting weights in PyTorch\n\n```python\nimport torchvision\nfrom safetensors import torch as stt\n\nmodel = torchvision.models.resnet18(pretrained=True)\nstt.save_file(model.state_dict(), 'resnet18.safetensors')\n```\n\n*Note: the filename of the export must be named with  a `.safetensors` suffix for it to be properly decoded by `tch`.*\n\n#### Importing weights in `tch`\n\n```rust\nuse anyhow::Result;\nuse tch::{\n\tDevice,\n\tKind,\n\tnn::VarStore,\n\tvision::{\n\t\timagenet,\n\t\tresnet::resnet18,\n\t}\n};\n\nfn main() -> Result\u003C()> {\n\t\u002F\u002F Create the model and load the pre-trained weights\n\tlet mut vs = VarStore::new(Device::cuda_if_available());\n\tlet model = resnet18(&vs.root(), 1000);\n\tvs.load(\"resnet18.safetensors\")?;\n\t\n\t\u002F\u002F Load the image file and resize it to the usual imagenet dimension of 224x224.\n\tlet image = imagenet::load_image_and_resize224(\"dog.jpg\")?\n\t\t.to_device(vs.device());\n\n\t\u002F\u002F Apply the forward pass of the model to get the logits\n\tlet output = image\n\t\t.unsqueeze(0)\n\t\t.apply_t(&model, false)\n\t\t.softmax(-1, Kind::Float);\n\t\n\t\u002F\u002F Print the top 5 categories for this image.\n    for (probability, class) in imagenet::top(&output, 5).iter() {\n        println!(\"{:50} {:5.2}%\", class, 100.0 * probability)\n    }\n    \n    Ok(())\n}\n```\n\nFurther examples include:\n* A simplified version of\n  [char-rnn](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Fchar-rnn)\n  illustrating character level language modeling using Recurrent Neural Networks.\n* [Neural style transfer](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Fneural-style-transfer)\n  uses a pre-trained VGG-16 model to compose an image in the style of another image (pre-trained weights:\n  [vgg16.ot](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Freleases\u002Fdownload\u002Fmw\u002Fvgg16.ot)).\n* Some [ResNet examples on CIFAR-10](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fcifar).\n* A [tutorial](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fjit)\n  showing how to deploy\u002Frun some Python trained models using\n  [TorchScript JIT](https:\u002F\u002Fpytorch.org\u002Fdocs\u002Fstable\u002Fjit.html).\n* Some [Reinforcement Learning](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Freinforcement-learning)\n  examples using the [OpenAI Gym](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fgym) environment. This includes a policy gradient\n  example as well as an A2C implementation that can run on Atari games.\n* A [Transfer Learning Tutorial](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Ftransfer-learning)\n  shows how to finetune a pre-trained ResNet model on a very small dataset.\n* A [simplified version of GPT](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Fmin-gpt)\n  similar to minGPT.\n* A [Stable Diffusion](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Fdiffusers-rs)\n  implementation following the lines of hugginface's diffusers library.\n\nExternal material:\n* A [tutorial](http:\u002F\u002Fvegapit.com\u002Farticle\u002Fhow-to-use-torch-in-rust-with-tch-rs) showing how to use Torch to compute option prices and greeks.\n* [tchrs-opencv-webcam-inference](https:\u002F\u002Fgithub.com\u002Fmetobom\u002Ftchrs-opencv-webcam-inference) uses `tch-rs` and `opencv` to run inference\n  on a webcam feed for some Python trained model based on mobilenet v3.\n\n## FAQ\n\n### What are the best practices for Python to Rust model translations?\n\nSee some details in [this thread](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F549#issuecomment-1296840898).\n\n### How to get this to work on a M1\u002FM2 mac?\n\nCheck this [issue](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F488).\n\n### Compilation is slow, torch-sys seems to be rebuilt every time cargo gets run.\nSee this [issue](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F596), this could\nbe caused by rust-analyzer not knowing about the proper environment variables\nlike `LIBTORCH` and `LD_LIBRARY_PATH`.\n\n### Using Rust\u002Ftch code from Python.\nIt is possible to call Rust\u002Ftch code from Python via PyO3,\n[tch-ext](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-ext) provides an example of such\na Python extension.\n\n### Error loading shared libraries. \n\nIf you get an error about not finding some shared libraries when running the generated binaries\n(e.g. \n` error while loading shared libraries: libtorch_cpu.so: cannot open shared object file: No such file or directory`).\nYou can try adding the following to your `.bashrc` where `\u002Fpath\u002Fto\u002Flibtorch` is the path to your\nlibtorch install.\n```\n# For Linux\nexport LD_LIBRARY_PATH=\u002Fpath\u002Fto\u002Flibtorch\u002Flib:$LD_LIBRARY_PATH\n# For macOS\nexport DYLD_LIBRARY_PATH=\u002Fpath\u002Fto\u002Flibtorch\u002Flib:$DYLD_LIBRARY_PATH\n```\n\n## License\n`tch-rs` is distributed under the terms of both the MIT license\nand the Apache license (version 2.0), at your option.\n\nSee [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT) for more\ndetails.\n","# tch-rs\nPyTorch C++ API 的 Rust 绑定。`tch` crate 的目标是为 PyTorch 的 C++ API（即 libtorch）提供一些轻量级的封装。它力求尽可能贴近原始的 C++ API，以便在此基础上进一步开发更符合 Rust 习惯的绑定。相关文档可在 docs.rs 上找到。\n\n[![构建状态](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fworkflows\u002FContinuous%20integration\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Factions)\n[![最新版本](https:\u002F\u002Fimg.shields.io\u002Fcrates\u002Fv\u002Ftch.svg)](https:\u002F\u002Fcrates.io\u002Fcrates\u002Ftch)\n[![文档](https:\u002F\u002Fdocs.rs\u002Ftch\u002Fbadge.svg)](https:\u002F\u002Fdocs.rs\u002Ftch)\n[![依赖状态](https:\u002F\u002Fdeps.rs\u002Frepo\u002Fgithub\u002FLaurentMazare\u002Ftch-rs\u002Fstatus.svg)](https:\u002F\u002Fdeps.rs\u002Frepo\u002Fgithub\u002FLaurentMazare\u002Ftch-rs)\n![许可证](https:\u002F\u002Fimg.shields.io\u002Fcrates\u002Fl\u002Ftch.svg)\n[变更日志](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmain\u002FCHANGELOG.md)\n\n\n基于 libtorch 的 C API 代码生成部分源自 [ocaml-torch](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Focaml-torch)。\n\n## 快速入门\n\n本 crate 需要系统中已安装 *v2.11.0* 版本的 PyTorch C++ 库（libtorch）。您可以选择以下方式之一：\n\n- 使用系统全局的 libtorch 安装（默认）。\n- 手动安装 libtorch，并通过 `LIBTORCH` 环境变量告知构建脚本其位置。\n- 使用 Python 安装的 PyTorch，为此设置 `LIBTORCH_USE_PYTORCH=1`。\n- 如果无法找到系统全局的 libtorch 且未设置 `LIBTORCH`，构建脚本可以通过启用 `download-libtorch` 功能下载预编译的 libtorch 二进制文件。默认使用 CPU 版本；可通过设置 `TORCH_CUDA_VERSION` 环境变量为 `cu117` 来获取使用 CUDA 11.7 的预编译二进制文件。\n\n### 系统全局的 Libtorch\n\n在 Linux 平台上，构建脚本会在 `\u002Fusr\u002Flib\u002Flibtorch.so` 中查找系统全局的 libtorch 库。\n\n### Python PyTorch 安装\n\n如果设置了 `LIBTORCH_USE_PYTORCH` 环境变量，则会调用当前激活的 Python 解释器来获取 torch Python 包的相关信息，并链接到该版本。\n\n### 手动安装 Libtorch\n\n- 从 [PyTorch 官网的下载页面](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F) 获取 `libtorch`，并解压 ZIP 文件。\n- 对于 Linux 和 macOS 用户，在 `.bashrc` 或等效配置文件中添加以下内容，其中 `\u002Fpath\u002Fto\u002Flibtorch` 是解压后创建的目录路径：\n```bash\nexport LIBTORCH=\u002Fpath\u002Fto\u002Flibtorch\n```\n还可以分别指定头文件和共享库的位置：\n```bash\n# LIBTORCH_INCLUDE 必须包含 `include` 目录。\nexport LIBTORCH_INCLUDE=\u002Fpath\u002Fto\u002Flibtorch\u002F\n# LIBTORCH_LIB 必须包含 `lib` 目录。\nexport LIBTORCH_LIB=\u002Fpath\u002Fto\u002Flibtorch\u002F\n```\n- 对于 Windows 用户，假设 `X:\\path\\to\\libtorch` 是解压后的 libtorch 目录：\n    - 打开控制面板 -> 查看高级系统设置 -> 环境变量。\n    - 创建 `LIBTORCH` 变量并将其设置为 `X:\\path\\to\\libtorch`。\n    - 将 `X:\\path\\to\\libtorch\\lib` 追加到 `Path` 变量中。\n  \n  如果您希望临时设置环境变量，可以在 PowerShell 中运行：\n```powershell\n$Env:LIBTORCH = \"X:\\path\\to\\libtorch\"\n$Env:Path += \";X:\\path\\to\\libtorch\\lib\"\n```\n- 此时您应该可以运行一些示例，例如 `cargo run --example basics`。\n\n### Windows 特别说明\n\n根据 [PyTorch 文档](https:\u002F\u002Fpytorch.org\u002Fcppdocs\u002Finstalling.html)，Windows 下的 Debug 和 Release 构建不兼容 ABI。如果使用了错误版本的 libtorch，可能会导致段错误。\n\n建议使用 MSVC Rust 工具链（例如通过 `rustup install stable-x86_64-pc-windows-msvc` 安装），而不是基于 MinGW 的工具链，因为 PyTorch 与 MinGW 存在兼容性问题。\n\n### 静态链接\n\n当设置环境变量 `LIBTORCH_STATIC=1` 时，将静态链接 libtorch，而非使用动态库。预编译的工件默认不包含 `libtorch.a`，因此需要手动编译，例如：\n```bash\ngit clone -b v2.11.0 --recurse-submodule https:\u002F\u002Fgithub.com\u002Fpytorch\u002Fpytorch.git pytorch-static --depth 1\ncd pytorch-static\nUSE_CUDA=OFF BUILD_SHARED_LIBS=OFF python setup.py build\n# 将 LIBTORCH 导出指向 pytorch-static 中的构建目录。\n```\n\n## 示例\n\n### 基本张量操作\n\n本 crate 提供了一个包装 PyTorch 张量的 Tensor 类型。以下是一个执行基本张量操作的最小示例。\n\n```rust\nuse tch::Tensor;\n\nfn main() {\n    let t = Tensor::from_slice(&[3, 1, 4, 1, 5]);\n    let t = t * 2;\n    t.print();\n}\n```\n\n### 使用梯度下降训练模型\n\nPyTorch 为其支持的大多数张量运算提供了自动微分功能，这通常用于通过梯度下降训练模型。优化过程是在通过 `nn::VarStore` 创建的变量上进行的，这些变量需要定义其形状和初始值。\n\n在下面的示例中，`my_module` 使用两个变量 `x1` 和 `x2`，它们的初始值均为 0。前向传播作用于张量 `xs` 后，返回 `xs * x1 + exp(xs) * x2`。\n\n模型生成后，创建一个 `nn::Sgd` 优化器。在训练循环的每一步中：\n\n- 对一个小批量数据应用前向传播。\n- 计算损失，即模型输出与小批量真实标签之间的均方误差。\n- 最后执行一次优化步骤：计算梯度，并相应地更新 `VarStore` 中的变量。\n\n\n```rust\nuse tch::nn::{Module, OptimizerConfig};\nuse tch::{kind, nn, Device, Tensor};\n\nfn my_module(p: nn::Path, dim: i64) -> impl nn::Module {\n    let x1 = p.zeros(\"x1\", &[dim]);\n    let x2 = p.zeros(\"x2\", &[dim]);\n    nn::func(move |xs| xs * &x1 + xs.exp() * &x2)\n}\n\nfn gradient_descent() {\n    let vs = nn::VarStore::new(Device::Cpu);\n    let my_module = my_module(vs.root(), 7);\n    let mut opt = nn::Sgd::default().build(&vs, 1e-2).unwrap();\n    for _idx in 1..50 {\n        \u002F\u002F 由零组成的虚拟小批量。\n        let xs = Tensor::zeros(&[7], kind::FLOAT_CPU);\n        let ys = Tensor::zeros(&[7], kind::FLOAT_CPU);\n        let loss = (my_module.forward(&xs) - ys).pow_tensor_scalar(2).sum(kind::Kind::Float);\n        opt.backward_step(&loss);\n    }\n}\n```\n\n### 编写一个简单的神经网络\n\n`nn` API 可以用于构建神经网络架构。例如，以下代码定义了一个包含一个隐藏层的简单模型，并使用 Adam 优化器在 MNIST 数据集上对其进行训练。\n\n```rust\nuse anyhow::Result;\nuse tch::{nn, nn::Module, nn::OptimizerConfig, Device};\n\nconst IMAGE_DIM: i64 = 784;\nconst HIDDEN_NODES: i64 = 128;\nconst LABELS: i64 = 10;\n\nfn net(vs: &nn::Path) -> impl Module {\n    nn::seq()\n        .add(nn::linear(\n            vs \u002F \"layer1\",\n            IMAGE_DIM,\n            HIDDEN_NODES,\n            Default::default(),\n        ))\n        .add_fn(|xs| xs.relu())\n        .add(nn::linear(vs, HIDDEN_NODES, LABELS, Default::default()))\n}\n\npub fn run() -> Result\u003C()> {\n    let m = tch::vision::mnist::load_dir(\"data\")?;\n    let vs = nn::VarStore::new(Device::Cpu);\n    let net = net(&vs.root());\n    let mut opt = nn::Adam::default().build(&vs, 1e-3)?;\n    for epoch in 1..200 {\n        let loss = net\n            .forward(&m.train_images)\n            .cross_entropy_for_logits(&m.train_labels);\n        opt.backward_step(&loss);\n        let test_accuracy = net\n            .forward(&m.test_images)\n            .accuracy_for_logits(&m.test_labels);\n        println!(\n            \"epoch: {:4} train loss: {:8.5} test acc: {:5.2}%\",\n            epoch,\n            f64::from(&loss),\n            100. * f64::from(&test_accuracy),\n        );\n    }\n    Ok(())\n}\n```\n\n有关训练循环的更多详细信息，请参阅[详细教程](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fmnist)。\n\n### 使用预训练模型\n\n[pretrained-models 示例](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fpretrained-models\u002Fmain.rs)展示了如何在图像上使用一些预训练的计算机视觉模型。这些权重是从 PyTorch 实现中提取的，可以在这里下载：[resnet18.ot](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Freleases\u002Fdownload\u002Fmw\u002Fresnet18.ot) 和 [resnet34.ot](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Freleases\u002Fdownload\u002Fmw\u002Fresnet34.ot)。\n\n然后可以通过以下命令运行该示例：\n```bash\ncargo run --example pretrained-models -- resnet18.ot tiger.jpg\n```\n这将打印出图像对应的 ImageNet 前 5 类别及其概率。该示例的代码非常简单。\n\n```rust\n    \u002F\u002F 首先加载图像并将其调整为 224x224 大小。\n    let image = imagenet::load_image_and_resize(image_file)?;\n\n    \u002F\u002F 创建一个变量存储来保存模型参数。\n    let vs = tch::nn::VarStore::new(tch::Device::Cpu);\n\n    \u002F\u002F 然后在此变量存储上构建模型，并加载权重。\n    let resnet18 = tch::vision::resnet::resnet18(vs.root(), imagenet::CLASS_COUNT);\n    vs.load(weight_file)?;\n\n    \u002F\u002F 对模型执行前向传播以获得 logits，并通过 softmax 将其转换为概率。\n    let output = resnet18\n        .forward_t(&image.unsqueeze(0), \u002F*train=*\u002F false)\n        .softmax(-1);\n\n    \u002F\u002F 最后打印出前 5 类别及其对应的概率。\n    for (probability, class) in imagenet::top(&output, 5).iter() {\n        println!(\"{:50} {:5.2}%\", class, 100.0 * probability)\n    }\n```\n\n### 使用 SafeTensors 从 PyTorch 导入预训练权重\n\n`safetensors` 是 HuggingFace 推出的一种新的简单张量存储格式。它不依赖于 Python 的 `pickle` 模块，因此张量不会绑定到保存模型时使用的特定类和确切的目录结构。此外，它是零拷贝的，这意味着读取文件所需的内存与原始文件大小相同。\n\n有关 `safetensors` 的更多信息，请参阅：https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsafetensors\n\n#### 安装 `safetensors`\n\n您可以通过 pip 包管理器安装 `safetensors`：\n\n```\npip install safetensors\n```\n\n#### 在 PyTorch 中导出权重\n\n```python\nimport torchvision\nfrom safetensors import torch as stt\n\nmodel = torchvision.models.resnet18(pretrained=True)\nstt.save_file(model.state_dict(), 'resnet18.safetensors')\n```\n\n*注意：导出文件的文件名必须以 `.safetensors` 为后缀，这样才能被 `tch` 正确解码。*\n\n#### 在 `tch` 中导入权重\n\n```rust\nuse anyhow::Result;\nuse tch::{\n\tDevice,\n\tKind,\n\tnn::VarStore,\n\tvision::{\n\t\timagenet,\n\t\tresnet::resnet18,\n\t}\n};\n\nfn main() -> Result\u003C()> {\n\t\u002F\u002F 创建模型并加载预训练权重\n\tlet mut vs = VarStore::new(Device::cuda_if_available());\n\tlet model = resnet18(&vs.root(), 1000);\n\tvs.load(\"resnet18.safetensors\")?;\n\t\n\t\u002F\u002F 加载图像文件，并将其调整为 ImageNet 常用的 224x224 尺寸。\n\tlet image = imagenet::load_image_and_resize224(\"dog.jpg\")?\n\t\t.to_device(vs.device());\n\n\t\u002F\u002F 对模型进行前向传播，得到 logits\n\tlet output = image\n\t\t.unsqueeze(0)\n\t\t.apply_t(&model, false)\n\t\t.softmax(-1, Kind::Float);\n\t\n\t\u002F\u002F 打印该图像的前 5 类别。\n    for (probability, class) in imagenet::top(&output, 5).iter() {\n        println!(\"{:50} {:5.2}%\", class, 100.0 * probability)\n    }\n    \n    Ok(())\n}\n```\n\n更多示例包括：\n* 一个简化的 [char-rnn](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Fchar-rnn) 示例，展示了使用循环神经网络进行字符级语言建模。\n* [神经风格迁移](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Fneural-style-transfer) 使用预训练的 VGG-16 模型，将一张图像转换为另一张图像的风格（预训练权重：[vgg16.ot](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Freleases\u002Fdownload\u002Fmw\u002Fvgg16.ot)）。\n* 一些在 CIFAR-10 数据集上的 [ResNet 示例](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fcifar)。\n* 一个 [教程](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fjit)，演示如何使用 [TorchScript JIT](https:\u002F\u002Fpytorch.org\u002Fdocs\u002Fstable\u002Fjit.html) 部署和运行由 Python 训练的模型。\n* 一些使用 [OpenAI Gym](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fgym) 环境的 [强化学习示例](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Freinforcement-learning)，其中包括策略梯度示例以及可在 Atari 游戏上运行的 A2C 实现。\n* 一个 [迁移学习教程](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Ftransfer-learning)，展示了如何在一个非常小的数据集上对预训练的 ResNet 模型进行微调。\n* 一个类似于 minGPT 的 [简化版 GPT](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Fmin-gpt)。\n* 一个遵循 HuggingFace diffusers 库思路的 [Stable Diffusion](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Fdiffusers-rs) 实现。\n\n外部资料：\n* 一个 [教程](http:\u002F\u002Fvegapit.com\u002Farticle\u002Fhow-to-use-torch-in-rust-with-tch-rs)，展示如何使用 Torch 计算期权价格和希腊字母。\n* [tchrs-opencv-webcam-inference](https:\u002F\u002Fgithub.com\u002Fmetobom\u002Ftchrs-opencv-webcam-inference) 使用 `tch-rs` 和 `opencv` 对基于 mobilenet v3 的 Python 训练模型进行网络摄像头推理。\n\n## 常见问题解答\n\n### 从 Python 到 Rust 模型转换的最佳实践是什么？\n\n请参阅 [此讨论](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F549#issuecomment-1296840898) 以获取详细信息。\n\n### 如何在 M1\u002FM2 Mac 上运行此代码？\n\n请查看 [此问题](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F488)。\n\n### 编译速度很慢，每次运行 cargo 时似乎都会重新构建 torch-sys。\n请参阅 [此问题](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F596)，这可能是由于 rust-analyzer 不了解正确的环境变量（如 `LIBTORCH` 和 `LD_LIBRARY_PATH`）所致。\n\n### 从 Python 调用 Rust\u002Ftch 代码。\n可以通过 PyO3 从 Python 调用 Rust\u002Ftch 代码，[tch-ext](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-ext) 提供了一个这样的 Python 扩展示例。\n\n### 加载共享库时出错。\n\n如果您在运行生成的二进制文件时遇到找不到某些共享库的错误（例如：\n`error while loading shared libraries: libtorch_cpu.so: cannot open shared object file: No such file or directory`），\n您可以尝试将以下内容添加到您的 `.bashrc` 文件中，其中 `\u002Fpath\u002Fto\u002Flibtorch` 是您 libtorch 的安装路径。\n```\n# 对于 Linux\nexport LD_LIBRARY_PATH=\u002Fpath\u002Fto\u002Flibtorch\u002Flib:$LD_LIBRARY_PATH\n# 对于 macOS\nexport DYLD_LIBRARY_PATH=\u002Fpath\u002Fto\u002Flibtorch\u002Flib:$DYLD_LIBRARY_PATH\n```\n\n## 许可证\n`tch-rs` 根据您的选择，同时采用 MIT 许可证和 Apache 许可证（版本 2.0）进行分发。\n\n有关详细信息，请参阅 [LICENSE-APACHE](LICENSE-APACHE) 和 [LICENSE-MIT](LICENSE-MIT)。","# tch-rs 快速上手指南\n\n`tch-rs` 是 PyTorch C++ API (libtorch) 的 Rust 绑定库。它旨在提供轻量级的封装，尽可能贴近原始的 C++ 接口，让 Rust 开发者能够利用 PyTorch 的强大功能进行深度学习开发。\n\n## 环境准备\n\n### 系统要求\n- **Rust**: 建议安装最新稳定版 (`rustup`)。\n- **操作系统**: Linux, macOS, Windows。\n- **编译器**:\n    - **Linux\u002FmacOS**: GCC 或 Clang。\n    - **Windows**: 强烈推荐使用 **MSVC** 工具链 (例如 `stable-x86_64-pc-windows-msvc`)。MinGW 可能与 PyTorch 存在兼容性问题。\n\n### 核心依赖：LibTorch\n本库依赖 C++ 版的 PyTorch 库 (**libtorch**)，版本需为 **v2.11.0**。你有以下几种方式获取：\n\n1.  **自动下载（推荐新手）**：启用 `download-libtorch` 特性，构建脚本会自动下载预编译的二进制文件。\n2.  **使用现有 Python 环境**：如果你已安装 `torch` Python 包，可复用其底层库。\n3.  **手动安装**：从官网下载并配置环境变量。\n\n> **国内加速提示**：如果自动下载速度慢，建议先手动下载 libtorch 压缩包（见下文“手动安装”），或通过设置环境变量指向国内镜像源下载的文件。\n\n## 安装步骤\n\n### 方法一：自动下载（最简单）\n\n在 `Cargo.toml` 中添加依赖并启用下载特性：\n\n```toml\n[dependencies]\ntch = { version = \"0.15\", features = [\"download-libtorch\"] }\n```\n\n*注：默认下载 CPU 版本。如需 CUDA 支持，请在运行 cargo 前设置环境变量：*\n```bash\nexport TORCH_CUDA_VERSION=cu117\ncargo build\n```\n\n### 方法二：复用 Python PyTorch 环境\n\n如果你已经通过 pip 安装了 PyTorch：\n\n1.  确保 `torch` 已安装：`pip install torch`\n2.  在 `Cargo.toml` 中仅添加依赖（无需特殊 feature）：\n    ```toml\n    [dependencies]\n    tch = \"0.15\"\n    ```\n3.  构建前设置环境变量告诉构建脚本使用 Python 的库：\n    ```bash\n    export LIBTORCH_USE_PYTORCH=1\n    cargo build\n    ```\n\n### 方法三：手动安装 LibTorch\n\n1.  **下载**：访问 [PyTorch 官网下载页](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F) 或国内镜像，下载 **LibTorch (C++)** 版本 **v2.11.0** (选择对应的 CPU 或 CUDA 版本)。\n2.  **解压**：将下载的 zip 文件解压到本地目录，例如 `\u002Fpath\u002Fto\u002Flibtorch`。\n3.  **配置环境变量**：\n\n    **Linux \u002F macOS**:\n    在 `.bashrc` 或 `.zshrc` 中添加：\n    ```bash\n    export LIBTORCH=\u002Fpath\u002Fto\u002Flibtorch\n    # 如果需要区分头文件和库文件路径（通常不需要，指向根目录即可）\n    # export LIBTORCH_INCLUDE=\u002Fpath\u002Fto\u002Flibtorch\u002Finclude\n    # export LIBTORCH_LIB=\u002Fpath\u002Fto\u002Flibtorch\u002Flib\n    ```\n    然后执行 `source ~\u002F.bashrc`。\n\n    **Windows (PowerShell)**:\n    ```powershell\n    $Env:LIBTORCH = \"X:\\path\\to\\libtorch\"\n    $Env:Path += \";X:\\path\\to\\libtorch\\lib\"\n    ```\n    *(永久设置可在“系统属性 -> 环境变量”中配置 `LIBTORCH` 变量，并将 `lib` 目录追加到 `Path` 中)*\n\n4.  **构建项目**：\n    ```bash\n    cargo build\n    ```\n\n## 基本使用\n\n### 1. 基础张量操作\n\n创建一个简单的张量并进行数学运算：\n\n```rust\nuse tch::Tensor;\n\nfn main() {\n    \u002F\u002F 从切片创建张量\n    let t = Tensor::from_slice(&[3, 1, 4, 1, 5]);\n    \n    \u002F\u002F 执行乘法操作\n    let t = t * 2;\n    \n    \u002F\u002F 打印结果\n    t.print();\n}\n```\n\n### 2. 简单的梯度下降训练\n\n利用 `tch` 的自动微分功能训练一个简单的模型：\n\n```rust\nuse tch::nn::{Module, OptimizerConfig};\nuse tch::{kind, nn, Device, Tensor};\n\n\u002F\u002F 定义一个简单的模块：f(x) = x * x1 + exp(x) * x2\nfn my_module(p: nn::Path, dim: i64) -> impl nn::Module {\n    let x1 = p.zeros(\"x1\", &[dim]);\n    let x2 = p.zeros(\"x2\", &[dim]);\n    nn::func(move |xs| xs * &x1 + xs.exp() * &x2)\n}\n\nfn gradient_descent() {\n    \u002F\u002F 创建变量存储区\n    let vs = nn::VarStore::new(Device::Cpu);\n    \n    \u002F\u002F 实例化模型\n    let my_module = my_module(vs.root(), 7);\n    \n    \u002F\u002F 创建 SGD 优化器\n    let mut opt = nn::Sgd::default().build(&vs, 1e-2).unwrap();\n    \n    \u002F\u002F 训练循环\n    for _idx in 1..50 {\n        \u002F\u002F 构造虚拟数据 (全零)\n        let xs = Tensor::zeros(&[7], kind::FLOAT_CPU);\n        let ys = Tensor::zeros(&[7], kind::FLOAT_CPU);\n        \n        \u002F\u002F 前向传播并计算损失 (MSE)\n        let loss = (my_module.forward(&xs) - ys).pow_tensor_scalar(2).sum(kind::Kind::Float);\n        \n        \u002F\u002F 反向传播并更新参数\n        opt.backward_step(&loss);\n    }\n}\n\nfn main() {\n    gradient_descent();\n}\n```\n\n### 3. 运行示例\n\n安装完成后，你可以直接运行官方提供的示例来验证环境：\n\n```bash\n# 运行基础示例\ncargo run --example basics\n\n# 运行 MNIST 训练示例 (需准备数据)\ncargo run --example mnist\n```","某自动驾驶初创团队需要将基于 PyTorch 训练的感知模型部署到车载边缘计算单元，该单元对内存安全和执行延迟有极高要求。\n\n### 没有 tch-rs 时\n- 团队被迫使用 Python 运行时加载模型，导致启动慢且内存占用高，难以满足车规级系统的实时性标准。\n- 为了追求性能尝试用 C++ 重写推理逻辑，但手动管理 LibTorch 的指针和内存极易引发段错误，调试过程痛苦且耗时。\n- 核心算法逻辑分散在 Python 训练脚本和 C++ 推理引擎中，语言隔阂导致代码复用率低，迭代新功能时需反复跨语言对齐接口。\n- 缺乏 Rust 的编译期类型检查，许多张量维度不匹配或设备（CPU\u002FGPU）放置错误的 Bug 只能在运行时暴露，增加了路测风险。\n\n### 使用 tch-rs 后\n- 直接利用 tch-rs 在纯 Rust 环境中加载并运行 LibTorch 模型，去除了 Python 解释器开销，显著降低延迟并提升内存安全性。\n- tch-rs 提供了贴近 C++ API 的薄封装，让开发者能在享受 Rust 所有权机制自动管理内存的同时，无缝调用底层高性能算子。\n- 训练后的模型权重可直接由 Rust 程序加载，实现了从数据预处理、模型推理到后处理的全链路 Rust 化，统一了技术栈。\n- 借助 Rust 强大的类型系统，大部分张量操作错误在编译阶段即被拦截，确保了车载软件在复杂路况下的运行稳定性。\n\ntch-rs 成功 bridging 了 PyTorch 生态与 Rust 系统级编程优势，让高性能 AI 推理既安全又高效。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLaurentMazare_tch-rs_2dcae93e.png","LaurentMazare","Laurent Mazare","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FLaurentMazare_5309fbb1.jpg","Co-founder Kyutai & Gradium",null,"Paris, France","lmazare","http:\u002F\u002Flaurentmazare.github.io","https:\u002F\u002Fgithub.com\u002FLaurentMazare",[83,87,91,95,99,103,107,110],{"name":84,"color":85,"percentage":86},"Rust","#dea584",63.8,{"name":88,"color":89,"percentage":90},"C++","#f34b7d",19,{"name":92,"color":93,"percentage":94},"C","#555555",16.3,{"name":96,"color":97,"percentage":98},"OCaml","#ef7a08",0.7,{"name":100,"color":101,"percentage":102},"Python","#3572A5",0.1,{"name":104,"color":105,"percentage":106},"CMake","#DA3434",0,{"name":108,"color":109,"percentage":106},"Makefile","#427819",{"name":111,"color":112,"percentage":106},"Dune","#89421e",5350,419,"2026-04-14T15:13:46","Apache-2.0",4,"Linux, macOS, Windows","非必需。支持 CPU 默认运行；若需 GPU 加速，需安装对应 CUDA 版本的 libtorch（例如通过设置 TORCH_CUDA_VERSION=cu117 下载预编译二进制），具体显卡型号和显存大小取决于所运行的 PyTorch 模型需求，README 未指定硬性指标。","未说明",{"notes":122,"python":123,"dependencies":124},"1. 核心依赖是 C++ 版的 PyTorch (libtorch) v2.11.0。2. Windows 用户强烈建议使用 MSVC Rust 工具链而非 MinGW，且需注意 Debug 和 Release 版本的 ABI 不兼容问题。3. 可通过环境变量 LIBTORCH 手动指定路径，或启用 download-libtorch 特性自动下载（默认 CPU 版）。4. 若需静态链接，需手动编译 libtorch。5. 支持加载 SafeTensors 格式的预训练权重。","非必需。仅在设置 LIBTORCH_USE_PYTORCH=1 使用 Python PyTorch 安装模式时需要系统中已安装 Python 及 torch 包，否则可独立使用 C++ libtorch。",[125,126],"libtorch (v2.11.0)","Rust toolchain (推荐 MSVC for Windows)",[14],[129,130,131,132,133],"pytorch","rust","machine-learning","neural-network","deep-learning","2026-03-27T02:49:30.150509","2026-04-16T08:12:12.537502",[137,142,147,152,157,162],{"id":138,"question_zh":139,"answer_zh":140,"source_url":141},35705,"如何在 Windows 上配置 tch-rs 的编译环境？","在 Windows 上直接编译可能会遇到链接器标志传递的问题。建议的解决方案包括：\n1. 使用 WSL (Windows Subsystem for Linux) 进行开发，这是更安全的路径。\n2. 如果使用原生 Windows，需确保安装了 Visual Studio 并正确配置了 C++ 构建工具。\n3. 注意：目前 Cargo 传递任意链接器标志的功能仍在改进中，某些“黑客式”的配置可能暂时无法避免。如果可能，优先尝试在 WSL (如 Ubuntu 20.04\u002F22.04) 中安装 `build-essential` 和 `libtorch` CPU 版本进行编译。","https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F177",{"id":143,"question_zh":144,"answer_zh":145,"source_url":146},35706,"如何使用 Rust (tch) 编写 Python 模块或扩展？","可以通过以下方式实现：\n1. 使用官方提供的 `pyo3-tch` crate，它简化了基于 tch 的 Python 模块编写。示例代码可在 `tch-ext` 仓库中找到。\n2. 另一种方法是手动链接 `pytorch_python` 库，利用 `THPVariable_Wrap` 将 Tensor 包装并转移所有权给 Python，或使用 `THPVariable_Unpack` 获取 Tensor 对象指针。这通常需要修改底层库以支持 Python 变量头文件 (`python_variable.h`)。","https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F174",{"id":148,"question_zh":149,"answer_zh":150,"source_url":151},35707,"GRU 或 LSTM 的 zero_state 初始化形状错误导致运行失败怎么办？","这是一个已知问题，`GRU::zero_state` 缺少一个维度。解决方法是手动修正状态张量的形状：\n如果是双向 (bidirectional) GRU，第一个维度应为 `2 * num_layers`，否则为 `1 * num_layers`。\n修正后的代码逻辑如下：\n```rust\nlet dim = if self.config.bidirectional { 2 } else { 1 };\nlet shape = [dim * self.config.num_layers, batch_dim, self.hidden_dim];\nGRUState(Tensor::zeros(&shape, (Kind::Float, self.device)))\n```\n对于 LSTM 结构也存在类似问题，需按相同逻辑调整。维护者已推送修复以支持双向和多層 GRU。","https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F88",{"id":153,"question_zh":154,"answer_zh":155,"source_url":156},35708,"在 CentOS 7 或其他旧版 Linux 上遇到 libgomp 链接错误如何解决？","这通常是由于 GCC C++11 ABI 不兼容导致的。解决方法是下载预编译的 `pre-cxx11 abi` 版本的 libtorch，并设置以下环境变量：\n```bash\nexport LIBTORCH=\u002Fpath\u002Fto\u002Flibtorch\nexport LD_LIBRARY_PATH=${LIBTORCH}\u002Flib:$LD_LIBRARY_PATH\nexport LIBTORCH_CXX11_ABI=0\n```\n设置完成后，执行 `cargo clean` 清理缓存并重新编译即可解决 `libgomp-xxx.so.1 not found` 的警告或错误。","https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F95",{"id":158,"question_zh":159,"answer_zh":160,"source_url":161},35709,"如何在 WSL (Windows Subsystem for Linux) 中完整搭建 tch-rs 开发环境？","推荐步骤如下：\n1. 安装 WSL：在 PowerShell 运行 `wsl --install`，并选择安装 Ubuntu (如 20.04 或 22.04)。\n2. 安装构建工具：在 WSL 终端运行 `sudo apt install build-essential` (可选安装 `gdb` 用于调试)。\n3. 下载 libtorch：访问 PyTorch 官网下载 CPU 版本的 libtorch (如 `libtorch-shared-with-deps-2.0.0+cpu.zip`)。\n4. 解压到项目根目录或指定文件夹，并确保环境变量指向该路径（如果未自动检测）。\n此方法比直接在 Windows 上配置 Visual Studio 更稳定且出错率更低。","https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F142",{"id":163,"question_zh":164,"answer_zh":165,"source_url":141},35710,"模型训练时报 CUDA 相关错误，但我只安装了 CPU 版本的 libtorch，原因是什么？","如果你没有手动安装 libtorch 且未设置 `TORCH_CUDA_VERSION` 环境变量，构建过程会自动下载 CPU 版本的 libtorch。\n出现 CUDA 错误通常是因为：\n1. 你加载的模型是专门针对 CUDA 训练的，无法在 CPU 版本上运行。\n2. 或者环境中意外混入了 CUDA 相关的配置。\n解决方法：尝试手动安装匹配版本的 libtorch，或者确认模型是否真的需要 GPU。如果只需 CPU 推理，请确保使用的是纯 CPU 版本的 libtorch 且模型兼容。",[167],{"id":168,"version":169,"summary_zh":170,"released_at":171},280923,"mw","此版本用于存储一些计算机视觉模型的权重文件。","2022-04-02T08:45:15"]