[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-facebookresearch--shumai":3,"tool-facebookresearch--shumai":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 真正成长为懂上",156804,2,"2026-04-15T11:34:33",[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":77,"owner_email":77,"owner_twitter":77,"owner_website":78,"owner_url":79,"languages":80,"stars":105,"forks":106,"last_commit_at":107,"license":108,"difficulty_score":109,"env_os":110,"env_gpu":111,"env_ram":112,"env_deps":113,"category_tags":120,"github_topics":77,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":121,"updated_at":122,"faqs":123,"releases":149},7832,"facebookresearch\u002Fshumai","shumai","Fast Differentiable Tensor Library in JavaScript and TypeScript with Bun + Flashlight","shumai 是一个专为 JavaScript 和 TypeScript 开发者打造的高性能可微分张量库。它旨在解决前端及全栈工程师在尝试进行机器学习研发时，往往受限于 Python 生态或现有 JS 数学库性能不足、缺乏自动求导能力的痛点。通过让开发者直接使用熟悉的 Web 技术栈即可构建和训练神经网络模型，shumai 极大地降低了 AI 工程化的门槛。\n\n这款工具特别适合软件工程师、全栈开发者以及希望快速原型验证的研究人员使用。其核心亮点在于独特的技术架构：底层基于高性能 C++ 张量库 Flashlight（现依托 ArrayFire 后端），上层结合超快速的 JavaScript 运行时 Bun。这种组合不仅提供了极致的运算速度，支持 GPU 加速，还实现了完整的自动微分功能，并具备原生的网络通信能力，便于构建分布式或端云协同的 AI 应用。\n\n需要注意的是，shumai 目前仍处于实验阶段，主要支持 macOS 和 Linux 环境。尽管它在 CPU 后端优化上仍有提升空间，且正在积极拓展对 OpenCL 等更多后端的支持，但它已为希望在 JavaScript 生态中探索高","shumai 是一个专为 JavaScript 和 TypeScript 开发者打造的高性能可微分张量库。它旨在解决前端及全栈工程师在尝试进行机器学习研发时，往往受限于 Python 生态或现有 JS 数学库性能不足、缺乏自动求导能力的痛点。通过让开发者直接使用熟悉的 Web 技术栈即可构建和训练神经网络模型，shumai 极大地降低了 AI 工程化的门槛。\n\n这款工具特别适合软件工程师、全栈开发者以及希望快速原型验证的研究人员使用。其核心亮点在于独特的技术架构：底层基于高性能 C++ 张量库 Flashlight（现依托 ArrayFire 后端），上层结合超快速的 JavaScript 运行时 Bun。这种组合不仅提供了极致的运算速度，支持 GPU 加速，还实现了完整的自动微分功能，并具备原生的网络通信能力，便于构建分布式或端云协同的 AI 应用。\n\n需要注意的是，shumai 目前仍处于实验阶段，主要支持 macOS 和 Linux 环境。尽管它在 CPU 后端优化上仍有提升空间，且正在积极拓展对 OpenCL 等更多后端的支持，但它已为希望在 JavaScript 生态中探索高性能深度学习的项目提供了一个极具潜力的新选择。","\u003Cimg width=\"1276\" alt=\"Shumai\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffacebookresearch_shumai_readme_ef53796f883a.png\">\n\n---\n\nA [fast](#benchmarks), [network-connected](https:\u002F\u002Ffacebookresearch.github.io\u002Fshumai\u002Fmodules\u002Fnetwork.html), differentiable tensor library for TypeScript (and JavaScript).  Built with [bun](https:\u002F\u002Fbun.sh) + [flashlight](https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight) for software engineers and researchers alike.\n\n![shumai_big](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffacebookresearch_shumai_readme_3e5b55dc123e.gif)\n\n\n\n⚠️ *This is experimental software!* ⚠️\n\n[![docs](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-available-blue)](https:\u002F\u002Ffacebookresearch.github.io\u002Fshumai\u002F)\n[![build](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Factions\u002Fworkflows\u002Fbuild.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Factions\u002Fworkflows\u002Fbuild.yml)\n[![tests](https:\u002F\u002Fcircleci.com\u002Fgh\u002Ffacebookresearch\u002Fshumai.svg?style=shield)](https:\u002F\u002Fapp.circleci.com\u002Fpipelines\u002Fgithub\u002Ffacebookresearch\u002Fshumai)\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@shumai\u002Fshumai\u002Flatest)](https:\u002F\u002Fwww.npmjs.com\u002Fsettings\u002Fshumai\u002Fpackages)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1013580889940295730)](https:\u002F\u002Fdiscord.com\u002Fchannels\u002F1013580889940295730\u002F)\n![GitHub commit activity](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcommit-activity\u002Fw\u002Ffacebookresearch\u002Fshumai)\n[![GitHub](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Ffacebookresearch\u002Fshumai)](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fblob\u002Fmain\u002FLICENSE)\n\n---\n\n\n- [Usage](#usage)\n- [Install](#install)\n- [Build from source](#building-native-libraries-from-source)\n- [Benchmarks](#benchmarks)\n- [Contributing](#contributing)\n\n## Quickstart\nInstall [Bun](https:\u002F\u002Fbun.sh\u002F) and [ArrayFire](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire\u002Fwiki\u002FGetting-ArrayFire)\n\n\u003Cdetails>\u003Csummary>\u003Cstrong>For MacOS users:\u003C\u002Fstrong>\u003C\u002Fsummary>\n  \nYou can use [Homebrew](https:\u002F\u002Fbrew.sh) to install ArrayFire:\n  \n```bash\ncurl https:\u002F\u002Fbun.sh\u002Finstall | bash\nbrew install arrayfire\n```\n  \n\u003C\u002Fdetails>\n\n\u003Cdetails>\u003Csummary>\u003Cstrong>For Linux users:\u003C\u002Fstrong>\u003C\u002Fsummary>\n  \nIf you're running Ubuntu with **x86-64**, you can use the official distribution:\n  \n```bash\ncurl https:\u002F\u002Fbun.sh\u002Finstall | bash\nsudo apt install -y gnupg2 ca-certificates\nsudo apt-key adv --fetch-key https:\u002F\u002Frepo.arrayfire.com\u002FGPG-PUB-KEY-ARRAYFIRE-2020.PUB\necho \"deb https:\u002F\u002Frepo.arrayfire.com\u002Fdebian all main\" | sudo tee \u002Fetc\u002Fapt\u002Fsources.list.d\u002Farrayfire.list\nsudo apt update\nsudo apt install -y arrayfire-cpu3-dev arrayfire-cpu3-openblas\n```\n  \nIf you're running Ubuntu with **ARMv8**, you'll need to build from source:\n\n```bash\ncurl https:\u002F\u002Fbun.sh\u002Finstall | bash\nsudo apt remove libarrayfire-dev libarrayfire-cpu3 libarrayfire-cpu-dev\nsudo apt install -y libblas-dev liblapack-dev liblapacke-dev libfftw3-dev libboost-all-dev cmake make g++\ncd \u002Ftmp\nsudo rm -rf arrayfire\ngit clone https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire.git\ncd arrayfire\ncmake -Bbuild -DAF_BUILD_EXAMPLES=OFF -DCMAKE_BUILD_TYPE=Release -DAF_BUILD_UNIFIED=OFF -DAF_TEST_WITH_MTX_FILES=OFF -DBUILD_TESTING=OFF\nmake -j4 -Cbuild\nsudo make install -Cbuild\n```\n  \nOtherwise, see the official [ArrayFire installation guide.](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire\u002Fwiki\u002FGetting-ArrayFire)\n\u003C\u002Fdetails>\n\nthen run:\n```\nbun install @shumai\u002Fshumai\n```\nOnly macOS and Linux are supported. Linux installs default to GPU computation with CUDA, and macOS to CPU. Detailed install instructions [below](#install).\n\n*Install is work in progress*: [**please file an issue**](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fissues) if you run into problems.\n\n\n## Usage\n\nshumai will always attempt to use an attached GPU or accelerator; although CPU computation will use the ArrayFire CPU backend, which is not well-optimized.\n\nWe hope to support the ArrayFire OpenCL backend and other non-ArrayFire tensor backends soon.\n\nIf shumai seems unusually slow, please file an issue!\n\n**Standard array utilities:**\n\n\n```javascript\nimport * as sm from \"@shumai\u002Fshumai\"\n\n\u002F\u002F create a 1024 by 1024 tensor, randomly filled with normal distribution\nlet X = sm.randn([1024, 1024])\nlet W = sm.identity(1024)\nlet Y = X.matmul(W)\nconsole.log(Y.shape)\n```\n\n**Conversion to and from JavaScript native arrays:**\n\n```javascript\nconst data : Float32Array = new Float32Array(128)\nfor (let i = 0; i \u003C 128; ++i) {\n  data[i] = Math.random()\n}\n\nconst X : Tensor = sm.tensor(data)\nconst pi = sm.scalar(3.14)\nconst Y = X.mul(pi)\n\n\u002F\u002F tensors can be converted back to native JavaScript\nconst Y_data = Y.toFloat32Array()\n\n\u002F\u002F scalar tensors can be converted to JavaScript numbers\nconst total : number = X.sum().toFloat32()\n```\n\n**Gradients:**\n\n```javascript\nconst W = sm.randn([128, 128])\nW.requires_grad = true\n\nconst X = sm.randn([128, 128])\nconst diff = X.sub(W)\nconst mse = diff.mul(diff).sum()\nmse.backward()\n\nW.grad \u002F\u002F this gradient is now populated\n\n\u002F\u002F copy W without allowing gradient updates\nconst Y = W.detach()\nY.sum().backward() \u002F\u002F nothing changes\n\n```\n\nSome more examples can be found [here](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Ftree\u002Fmain\u002Fexamples).\n\nSupported operators can be found [here](#supported-operations).\n\n## Install\n\n**The install procedure is a work in progress!**\nIf you have any problems building or installing, we would\ngreatly appreciate filed issues. Please tell us about your platform\u002FOS when you do.\n\n**Prerequisites**:\n- Ensure you have bun installed (https:\u002F\u002Fbun.sh).\n- Install [ArrayFire](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire). *macOS users should install ArrayFire's CPU backend; Linux users should install the CUDA backend^.*\n  - **macOS** --- ArrayFire can easily be installed with Homebrew:\n  ```\n  brew install arrayfire\n  ```\n- **Linux** --- instructions [can be found here](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire\u002Fwiki\u002FGetting-ArrayFire). On Ubuntu, ArrayFire can be installed via [package managers (e.g. `apt`)](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire\u002Fwiki\u002FInstall-ArrayFire-From-Linux-Package-Managers).\n\nOnce `bun` and `ArrayFire` are installed, install the package and backing libs with `bun`:\n```shell\nbun install @shumai\u002Fshumai\n```\n\n### Windows Support\n\nWhile not officially supported, Windows users have been successful leveraging [Docker](https:\u002F\u002Fwww.docker.com\u002F) + [WSL2](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fwindows\u002Fwsl\u002Finstall) + Linux. Including CUDA support.\n\n\n## Building Native Libraries from Source\n\n**Note:** *not required when developing TypeScript\u002FJavascript library components locally.*\n\nFrom source build instructions for:\n- [macOS](#building-on-macos-from-source)\n- [Linux](#building-on-linux-from-source)\n\nThis process will build the dependent ffi libraries (`libflashlight` and `libflashlight_binding`) and pack them using `npm pack` to generate a `@shumai\u002Fshumai_*.tgz`\npackage. You can then use `npm install $PATH_TO_SOURCE\u002F@shumai\u002Fshumai-*.tgz` to install the package where you'd like.\n\n### Building on macOS from Source\n\nFirst, install ArrayFire CPU with `brew install arrayfire`.\n\nBuild and install [Flashlight](https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight#building-and-installing):\n```bash\nmkdir -p $HOME\u002Fusr\u002F # installing flashlight here\ngit clone --recursive --depth 1 https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight.git\ncd flashlight\nmkdir -p build\ncd build\ncmake .. \\\n  -DCMAKE_BUILD_TYPE=Release \\\n  -DBUILD_SHARED_LIBS=ON  \\\n  -DCMAKE_INSTALL_PREFIX=$HOME\u002Fusr \\\n  -DFL_USE_ARRAYFIRE=ON \\\n  -DFL_ARRAYFIRE_USE_CPU=ON \\\n  -DFL_USE_ONEDNN=OFF \\\n  -DFL_BUILD_DISTRIBUTED=OFF \\\n  -DFL_BUILD_TESTS=OFF \\\n  -DFL_BUILD_EXAMPLES=OFF\nmake -j$(nproc)\nmake install\n```\n\nBuild Flashlight bindings for Shumai:\n```bash\ncd shumai\nmkdir -p build\ncd build\ncmake .. -Dflashlight_DIR=$HOME\u002Fusr\u002Fshare\u002Fflashlight\u002Fcmake\u002F\nmake -j$(nproc)\n```\n\n#### Profiling\n\nOn macOS, you can record perf with `xcrun xctrace record --template \"Time Profiler\" --launch $(which bun) train.js`.\n\n### Building on Linux from Source\n\nFirst [install ArrayFire](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire\u002Fwiki\u002FGetting-ArrayFire). The Linux build for shumai uses the CUDA backend, but from source, you can build the CPU backend as well (OpenCL support coming soon).\n\nBuild and install [Flashlight](https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight#building-and-installing):\n```bash\nmkdir -p $HOME\u002Fusr\u002F # installing flashlight here\ngit clone --recursive --depth 1 https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight.git\ncd flashlight\nmkdir -p build\ncd build\ncmake .. \\\n  -DCMAKE_BUILD_TYPE=RelWithDebInfo \\ # or as specified\n  -DFL_ARRAYFIRE_USE_CPU=OFF \\\n  \\ # swap with the above to build for CPU\n  -DFL_ARRAYFIRE_USE_CUDA=ON \\ \n  -DFL_BUILD_DISTRIBUTED=OFF \\\n  -DFL_USE_ONEDNN=OFF \\\n  -DFL_BUILD_TESTS=OFF \\\n  -DFL_BUILD_EXAMPLES=OFF \\\n  -DFL_BUILD_SCRIPTS=OFF \\\n  -DCMAKE_INSTALL_PREFIX=$HOME\u002Fusr\u002F\nmake -j$(nproc)\nmake install\n```\n\nBuild bindings for shumai:\n```bash\nmkdir -p build && cd build\ncmake .. \\\n    -DBUILD_SHARED_LIBS=ON \\\n    -DCMAKE_BUILD_TYPE=RelWithDebInfo \\ # or as specified\n    -Dflashlight_DIR=${FLASHLIGHT_INSTALL_PREFIX}\u002Fshare\u002Fflashlight\u002Fcmake \\\n    -DArrayFire_DIR=${ARRAYFIRE_INSTALL_PREFIX}\u002Fshare\u002FArrayFire\u002Fcmake # if built from source, else not needed\nmake -j$(nproc)\n```\n\n\n\n## Why build this?\n\nWith Shumai, we hope to make \n\n- **Creating datasets easier**\n  - JavaScript, with native typed arrays and a JIT compiler, is perfect for twiddling with data before it can be made into big, flat GPU-compatible arrays.\n- **Training small models faster**\n  - FFI bindings in Bun are crazy fast (~3ns), so JS gets out of the way when training small models\n- **Advanced\u002Ffine-grained training\u002Finference logic more expressive**\n  - Bun uses the JSC JIT compiler, meaning you can confidently write complex training logic without needing a native C++ implementation\n- **Building applications enoyable**\n  - JavaScript has a ~~large~~ [HUGE](https:\u002F\u002Fsurvey.stackoverflow.co\u002F2022\u002F#section-most-popular-technologies-programming-scripting-and-markup-languages) ecosystem, which facilitates better application development\n  \n  \n## Benchmarks\n\nBenchmark data is collected from https:\u002F\u002Fgithub.com\u002Fshumai-org\u002Fbenchmarks\n\nOn an Apple M1 Pro:\n\n| Benchmark     | Shumai (bun)  | TF.js (node)  | Difference |\n| ------------- |---------------| --------------| -----------|\n| 32-wide addition | 624.78K iter\u002Fs | 195.627K iter\u002Fs | 3.19x |\n| 1024-wide addition | 460.008K iter\u002Fs | 94.945K iter\u002Fs | 4.84x |\n| 32768-wide addition | 57.929K iter\u002Fs | 40.484K iter\u002Fs | 1.43x |\n| 64-wide square matmul | 43 GFlop\u002Fs | 28.533 GFlop\u002Fs | 1.51x |\n| 128-wide square matmul | 518.704 GFlop\u002Fs | 58.764 GFlop\u002Fs | 8.83x |\n| 1024-wide square matmul | 2,147.771 GFlop\u002Fs | 318.826 GFlop\u002Fs | 6.74x |\n| B=64, 64-wide hidden layer + 5x pointwise |41.344K iter\u002Fs| 16.679K iter\u002Fs | 2.48x|\n| B=64, 128-wide hidden layer + 5x pointwise |24.554K iter\u002Fs| 8.563K iter\u002Fs | 2.87x|\n| B=64, 1024-wide hidden layer + 5x pointwise |2.716K iter\u002Fs| 0.969K iter\u002Fs | 2.80x|\n\nOn an Nvidia GP100:\n\n| Benchmark     | Shumai (bun)  | TF.js (node)  | Difference |\n| ------------- |---------------| --------------| -----------|\n| 32-wide addition | 243.217K iter\u002Fs | 34.539K iter\u002Fs | 7.04x |\n| 1024-wide addition | 144.771K iter\u002Fs | 18.006K iter\u002Fs | 8.04x |\n| 32768-wide addition | 71.793K iter\u002Fs | 17.071K iter\u002Fs | 4.21x |\n| 64-wide square matmul | 63.239 GFlop\u002Fs | 12.749 GFlop\u002Fs | 4.96x |\n| 128-wide square matmul | 435.565 GFlop\u002Fs | 104.885 GFlop\u002Fs | 4.15x |\n| 1024-wide square matmul | 7,165.062 GFlop\u002Fs | 6,470.793 GFlop\u002Fs | 1.11x |\n| B=64, 64-wide hidden layer + 5x pointwise |25.507K iter\u002Fs| 5.192K iter\u002Fs | 4.91x|\n| B=64, 128-wide hidden layer + 5x pointwise |22.529K iter\u002Fs| 4.861K iter\u002Fs | 4.63x|\n| B=64, 1024-wide hidden layer + 5x pointwise |11.568K iter\u002Fs| 2.854K iter\u002Fs | 4.05x|\n\n\n## Memory Usage\n\nWhile the out of the box memory management may suffice in many cases, tuning memory\nusage can greatly improve performance by reducing unnecessary overhead from the\nGarbage Collector.\n\n```\nimport { util } from '@shumai\u002Fshumai'\n\nutil.memoryOptions({\n  lowerBoundThreshold: 100e6, \u002F\u002F 100MB\n  upperBoundThreshold: 5e9, \u002F\u002F 5GB\n  delayBetweenGCs: 1000 \u002F\u002F 1s\n})\n```\n\nPay special attention to `upperBoundThreshold` which if exceeded will force GC\nfor every allocated tensor, ignoring `delayBetweenGCs`. Supplying a value that\nwill fully utilize your hardware can greatly improve performance.\n\n\n## Statistics\n\n```mermaid\ngraph TD\n  OpA(Op A) --> statsA{{\"stats A\"}};\n  OpB(Op B) --> statsA;\n  statsA --> LoggerA{{\"LoggerConsole A\"}};\n  LoggerA --> Stdout((\"Stdout\"));\n  OpC(Op C) --> statsA;\n  OpD(Op D) --> statsA;\n  statsA --> LoggerB(\"LoggerCustom B\");\n  LoggerB --> Disk((\"Disk\"));\n```\n\nBasic usage of gathering statistics is as simple adding\na collector using the default `StatsLoggerConsole`.\n\n```\nimport { stats, StatsLoggerConsole, rand, matmul } from '@shumai\u002Fshumai'\n\nstats.enabled = true \u002F\u002F all ops following will capture stats\n\n\u002F\u002F perform ops...\n\nstats.enabled = false \u002F\u002F all ops following will no longer capture stats\n```\n\nWhile the above examples may suffice for simple use cases, if you're\nlooking to capture stats across multiple threads, processes, and\u002For hosts,\n`StatsLoggerHttp` has you covered.\n\n```mermaid\ngraph TD\n  subgraph Host C\n    Processor(\"LoggerHttp Processor\")\n    style Processor stroke:#222,stroke-width:4px,stroke-dasharray:5 5\n  end\n  subgraph Host A\n    OpA(Op A) --> statsA{{\"stats A\"}};\n    OpB(Op B) --> statsA;\n    statsA --> LoggerA{{\"LoggerHttp A\"}};\n    LoggerA --> Processor;\n  end\n  subgraph Host B\n    OpC(Op C) --> statsB{{\"stats B\"}};\n    OpD(Op D) --> statsB;\n    statsB --> LoggerB{{\"LoggerHttp B\"}};\n    LoggerB --> Processor;\n  end\n```\n\n```\nimport { StatsLoggerHttp } from '@shumai\u002Fshumai'\n\nstats.logger = new StatsLoggerHttp({ url: 'http:\u002F\u002Flocalhost:4242' })\n```\n\nFor more custom needs you can supply your own logger:\n\n```\nimport { StatsLogger, StatsLoggerData } from '@shumai\u002Fshumai'\n\nclass CustomLogger implements StatsLogger {\n  async process(data: StatsLoggerData): Promise\u003Cvoid> {\n    const summary = data.collector.getSummary()\n    console.log('Collector stats:', summary)\n  }\n}\n\nstats.logger = new CustomLogger()\n```\n\nBy default stack tracing is disabled as it adds 50%+ overhead, but can be enabled via `stats.collectStacks = true`.\n\n### Scoped Statistics\n\nIf you wish to isolate stats profiling you can do this as well:\n\n```\nimport { collectStats } from '@shumai\u002Fshumai'\n\nconst scopedStats = collectStats(() => {\n  \u002F\u002F perform ops...\n}\u002F*, StatsCollectorOptions | StatsLogger *\u002F)\nconsole.log(scopedStats.getSummary())\n```\n\n\n## Contributing\n\nIf you'd like to make changes to the core bindings or ffi, first [build from source](#installing-from-source).\n\nAll files ending in `*.inl` or `*_gen.ts` are generated.\nThese can be modified by editing [`scripts\u002Fgen_binding.py`](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fblob\u002Fmain\u002Fscripts\u002Fgen_binding.py)\nand running [`.\u002Fscripts\u002Fgen_all_binding.sh`](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fblob\u002Fmain\u002Fscripts\u002Fgen_all_binding.sh).\n\nSee the [CONTRIBUTING](CONTRIBUTING.md) file for style guidance and more info on how to help out. 😁\n\n### License\n\nshumai is MIT licensed, as found in the LICENSE file.\n\n\n\n","\u003Cimg width=\"1276\" alt=\"烧麦\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffacebookresearch_shumai_readme_ef53796f883a.png\">\n\n---\n\n一个为 TypeScript（及 JavaScript）打造的、[快速](#benchmarks)、[支持网络连接](https:\u002F\u002Ffacebookresearch.github.io\u002Fshumai\u002Fmodules\u002Fnetwork.html)且可微分的张量库。基于 [bun](https:\u002F\u002Fbun.sh) 和 [flashlight](https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight) 构建，适用于软件工程师和研究人员。\n\n![shumai_big](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffacebookresearch_shumai_readme_3e5b55dc123e.gif)\n\n\n\n⚠️ *本项目为实验性软件！* ⚠️\n\n[![文档](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-available-blue)](https:\u002F\u002Ffacebookresearch.github.io\u002Fshumai\u002F)\n[![构建](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Factions\u002Fworkflows\u002Fbuild.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Factions\u002Fworkflows\u002Fbuild.yml)\n[![测试](https:\u002F\u002Fcircleci.com\u002Fgh\u002Ffacebookresearch\u002Fshumai.svg?style=shield)](https:\u002F\u002Fapp.circleci.com\u002Fpipelines\u002Fgithub\u002Ffacebookresearch\u002Fshumai)\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@shumai\u002Fshumai\u002Flatest)](https:\u002F\u002Fwww.npmjs.com\u002Fsettings\u002Fshumai\u002Fpackages)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1013580889940295730)](https:\u002F\u002Fdiscord.com\u002Fchannels\u002F1013580889940295730\u002F)\n![GitHub 提交活跃度](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcommit-activity\u002Fw\u002Ffacebookresearch\u002Fshumai)\n[![许可证](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Ffacebookresearch\u002Fshumai)](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fblob\u002Fmain\u002FLICENSE)\n\n---\n\n\n- [使用方法](#usage)\n- [安装](#install)\n- [从源码构建](#building-native-libraries-from-source)\n- [基准测试](#benchmarks)\n- [贡献](#contributing)\n\n## 快速入门\n安装 [Bun](https:\u002F\u002Fbun.sh\u002F) 和 [ArrayFire](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire\u002Fwiki\u002FGetting-ArrayFire)\n\n\u003Cdetails>\u003Csummary>\u003Cstrong>对于 macOS 用户：\u003C\u002Fstrong>\u003C\u002Fsummary>\n  \n您可以使用 [Homebrew](https:\u002F\u002Fbrew.sh) 安装 ArrayFire：\n  \n```bash\ncurl https:\u002F\u002Fbun.sh\u002Finstall | bash\nbrew install arrayfire\n```\n  \n\u003C\u002Fdetails>\n\n\u003Cdetails>\u003Csummary>\u003Cstrong>对于 Linux 用户：\u003C\u002Fstrong>\u003C\u002Fsummary>\n  \n如果您运行的是 **x86-64** 架构的 Ubuntu，可以使用官方提供的包管理器进行安装：\n  \n```bash\ncurl https:\u002F\u002Fbun.sh\u002Finstall | bash\nsudo apt install -y gnupg2 ca-certificates\nsudo apt-key adv --fetch-key https:\u002F\u002Frepo.arrayfire.com\u002FGPG-PUB-KEY-ARRAYFIRE-2020.PUB\necho \"deb https:\u002F\u002Frepo.arrayfire.com\u002Fdebian all main\" | sudo tee \u002Fetc\u002Fapt\u002Fsources.list.d\u002Farrayfire.list\nsudo apt update\nsudo apt install -y arrayfire-cpu3-dev arrayfire-cpu3-openblas\n```\n  \n如果您运行的是 **ARMv8** 架构的 Ubuntu，则需要从源码编译：\n\n```bash\ncurl https:\u002F\u002Fbun.sh\u002Finstall | bash\nsudo apt remove libarrayfire-dev libarrayfire-cpu3 libarrayfire-cpu-dev\nsudo apt install -y libblas-dev liblapack-dev liblapacke-dev libfftw3-dev libboost-all-dev cmake make g++\ncd \u002Ftmp\nsudo rm -rf arrayfire\ngit clone https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire.git\ncd arrayfire\ncmake -Bbuild -DAF_BUILD_EXAMPLES=OFF -DCMAKE_BUILD_TYPE=Release -DAF_BUILD_UNIFIED=OFF -DAF_TEST_WITH_MTX_FILES=OFF -DBUILD_TESTING=OFF\nmake -j4 -Cbuild\nsudo make install -Cbuild\n```\n  \n其他情况，请参考官方的 [ArrayFire 安装指南](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire\u002Fwiki\u002FGetting-ArrayFire)。\n\u003C\u002Fdetails>\n\n然后运行：\n```\nbun install @shumai\u002Fshumai\n```\n目前仅支持 macOS 和 Linux 系统。Linux 默认使用 CUDA 进行 GPU 计算，而 macOS 则使用 CPU。详细的安装说明请参见 [下方](#install)。\n\n*安装仍在开发中*：如果您遇到任何问题，请[提交 issue](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fissues)。\n\n## 使用方法\n\nshumai 会优先尝试使用连接的 GPU 或加速器；不过，CPU 计算将使用 ArrayFire 的 CPU 后端，该后端尚未经过充分优化。\n\n我们计划尽快支持 ArrayFire 的 OpenCL 后端以及其他非 ArrayFire 的张量后端。\n\n如果 shumai 运行速度异常缓慢，请提交 issue！\n\n**标准数组工具：**\n\n\n```javascript\nimport * as sm from \"@shumai\u002Fshumai\"\n\n\u002F\u002F 创建一个 1024x1024 的随机正态分布张量\nlet X = sm.randn([1024, 1024])\nlet W = sm.identity(1024)\nlet Y = X.matmul(W)\nconsole.log(Y.shape)\n```\n\n**与原生 JavaScript 数组之间的转换：**\n\n```javascript\nconst data : Float32Array = new Float32Array(128)\nfor (let i = 0; i \u003C 128; ++i) {\n  data[i] = Math.random()\n}\n\nconst X : Tensor = sm.tensor(data)\nconst pi = sm.scalar(3.14)\nconst Y = X.mul(pi)\n\n\u002F\u002F 张量可以转换回原生 JavaScript\nconst Y_data = Y.toFloat32Array()\n\n\u002F\u002F 标量张量可以转换为 JavaScript 数值\nconst total : number = X.sum().toFloat32()\n```\n\n**梯度：**\n\n```javascript\nconst W = sm.randn([128, 128])\nW.requires_grad = true\n\nconst X = sm.randn([128, 128])\nconst diff = X.sub(W)\nconst mse = diff.mul(diff).sum()\nmse.backward()\n\nW.grad \u002F\u002F 此时梯度已被填充\n\n\u002F\u002F 复制 W 但不允许更新梯度\nconst Y = W.detach()\nY.sum().backward() \u002F\u002F 不会发生任何变化\n\n```\n\n更多示例请参阅 [这里](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Ftree\u002Fmain\u002Fexamples)。\n\n支持的操作列表请参见 [此处](#supported-operations)。\n\n## 安装\n\n**安装流程仍在开发中！**\n如果您在构建或安装过程中遇到任何问题，我们非常感谢您提交 issue。请务必告知我们您的平台\u002F操作系统信息。\n\n**先决条件**：\n- 确保已安装 bun (https:\u002F\u002Fbun.sh)。\n- 安装 [ArrayFire](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire)。*macOS 用户应安装 ArrayFire 的 CPU 后端；Linux 用户则应安装 CUDA 后端^。*\n  - **macOS** --- 可以通过 Homebrew 轻松安装 ArrayFire：\n  ```\n  brew install arrayfire\n  ```\n- **Linux** --- 安装说明请参见 [此处](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire\u002Fwiki\u002FGetting-ArrayFire)。在 Ubuntu 上，可以通过包管理器（如 `apt`）安装 ArrayFire。\n  \n一旦 `bun` 和 `ArrayFire` 安装完毕，即可使用 `bun` 安装包及其依赖库：\n```shell\nbun install @shumai\u002Fshumai\n```\n\n### Windows 支持\n\n虽然未正式支持，但有用户成功利用 [Docker](https:\u002F\u002Fwww.docker.com\u002F) + [WSL2](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fwindows\u002Fwsl\u002Finstall) + Linux 环境来运行，甚至包括 CUDA 支持。\n\n\n## 从源码构建原生库\n\n**注意：** *在本地开发 TypeScript\u002FJavascript 库组件时无需执行此步骤。*\n\n以下是针对以下平台的源码构建说明：\n- [macOS](#building-on-macos-from-source)\n- [Linux](#building-on-linux-from-source)\n\n此过程将构建依赖的 FFI 库（`libflashlight` 和 `libflashlight_binding`），并使用 `npm pack` 将其打包成 `@shumai\u002Fshumai_*.tgz` 包。随后，您可以使用 `npm install $PATH_TO_SOURCE\u002F@shumai\u002Fshumai-*.tgz` 在任意位置安装该包。\n\n### 在 macOS 上从源码构建\n\n首先，使用 `brew install arrayfire` 安装 ArrayFire CPU 版本。\n\n构建并安装 [Flashlight](https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight#building-and-installing)：\n```bash\nmkdir -p $HOME\u002Fusr\u002F # 将 Flashlight 安装到这里\ngit clone --recursive --depth 1 https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight.git\ncd flashlight\nmkdir -p build\ncd build\ncmake .. \\\n  -DCMAKE_BUILD_TYPE=Release \\\n  -DBUILD_SHARED_LIBS=ON  \\\n  -DCMAKE_INSTALL_PREFIX=$HOME\u002Fusr \\\n  -DFL_USE_ARRAYFIRE=ON \\\n  -DFL_ARRAYFIRE_USE_CPU=ON \\\n  -DFL_USE_ONEDNN=OFF \\\n  -DFL_BUILD_DISTRIBUTED=OFF \\\n  -DFL_BUILD_TESTS=OFF \\\n  -DFL_BUILD_EXAMPLES=OFF\nmake -j$(nproc)\nmake install\n```\n\n为 Shumai 构建 Flashlight 绑定：\n```bash\ncd shumai\nmkdir -p build\ncd build\ncmake .. -Dflashlight_DIR=$HOME\u002Fusr\u002Fshare\u002Fflashlight\u002Fcmake\u002F\nmake -j$(nproc)\n```\n\n#### 性能分析\n\n在 macOS 上，你可以使用 `xcrun xctrace record --template \"Time Profiler\" --launch $(which bun) train.js` 来录制性能分析数据。\n\n### 在 Linux 上从源码构建\n\n首先[安装 ArrayFire](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire\u002Fwiki\u002FGetting-ArrayFire)。Shumai 的 Linux 构建默认使用 CUDA 后端，但如果你从源码编译，也可以构建 CPU 后端（OpenCL 支持即将推出）。\n\n构建并安装 [Flashlight](https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight#building-and-installing)：\n```bash\nmkdir -p $HOME\u002Fusr\u002F # 将 Flashlight 安装到这里\ngit clone --recursive --depth 1 https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight.git\ncd flashlight\nmkdir -p build\ncd build\ncmake .. \\\n  -DCMAKE_BUILD_TYPE=RelWithDebInfo \\ # 或根据需求指定\n  -DFL_ARRAYFIRE_USE_CPU=OFF \\\n  \\ # 切换为上述选项以构建 CPU 版本\n  -DFL_ARRAYFIRE_USE_CUDA=ON \\ \n  -DFL_BUILD_DISTRIBUTED=OFF \\\n  -DFL_USE_ONEDNN=OFF \\\n  -DFL_BUILD_TESTS=OFF \\\n  -DFL_BUILD_EXAMPLES=OFF \\\n  -DFL_BUILD_SCRIPTS=OFF \\\n  -DCMAKE_INSTALL_PREFIX=$HOME\u002Fusr\u002F\nmake -j$(nproc)\nmake install\n```\n\n构建 Shumai 的绑定：\n```bash\nmkdir -p build && cd build\ncmake .. \\\n    -DBUILD_SHARED_LIBS=ON \\\n    -DCMAKE_BUILD_TYPE=RelWithDebInfo \\ # 或根据需求指定\n    -Dflashlight_DIR=${FLASHLIGHT_INSTALL_PREFIX}\u002Fshare\u002Fflashlight\u002Fcmake \\\n    -DArrayFire_DIR=${ARRAYFIRE_INSTALL_PREFIX}\u002Fshare\u002FArrayFire\u002Fcmake # 如果是从源码构建，则需要；否则不需要\nmake -j$(nproc)\n```\n\n\n\n## 为什么要构建这个？\n\n借助 Shumai，我们希望实现以下目标：\n\n- **更轻松地创建数据集**\n  - JavaScript 拥有原生的类型化数组和 JIT 编译器，非常适合在将数据转换为大型、扁平化的 GPU 兼容数组之前进行数据处理。\n- **更快地训练小型模型**\n  - Bun 中的 FFI 绑定速度极快（约 3 纳秒），因此在训练小型模型时，JavaScript 不会成为瓶颈。\n- **更灵活、更精细的训练\u002F推理逻辑**\n  - Bun 使用 JSC JIT 编译器，这意味着你可以放心地编写复杂的训练逻辑，而无需依赖原生 C++ 实现。\n- **开发更具吸引力的应用程序**\n  - JavaScript 拥有一个~~庞大~~[巨大的](https:\u002F\u002Fsurvey.stackoverflow.co\u002F2022\u002F#section-most-popular-technologies-programming-scripting-and-markup-languages)生态系统，这有助于更好地进行应用程序开发。\n\n## 基准测试\n\n基准测试数据来自 https:\u002F\u002Fgithub.com\u002Fshumai-org\u002Fbenchmarks。\n\n在 Apple M1 Pro 上：\n\n| 基准测试     | Shumai (bun)  | TF.js (node)  | 差异 |\n| ------------- |---------------| --------------| -----------|\n| 32 宽度加法 | 624.78K 次\u002F秒 | 195.627K 次\u002F秒 | 3.19 倍 |\n| 1024 宽度加法 | 460.008K 次\u002F秒 | 94.945K 次\u002F秒 | 4.84 倍 |\n| 32768 宽度加法 | 57.929K 次\u002F秒 | 40.484K 次\u002F秒 | 1.43 倍 |\n| 64×64 方阵乘法 | 43 GFlop\u002Fs | 28.533 GFlop\u002Fs | 1.51 倍 |\n| 128×128 方阵乘法 | 518.704 GFlop\u002Fs | 58.764 GFlop\u002Fs | 8.83 倍 |\n| 1024×1024 方阵乘法 | 2,147.771 GFlop\u002Fs | 318.826 GFlop\u002Fs | 6.74 倍 |\n| B=64，64 宽度隐藏层 + 5 次逐点运算 | 41.344K 次\u002F秒 | 16.679K 次\u002F秒 | 2.48 倍 |\n| B=64，128 宽度隐藏层 + 5 次逐点运算 | 24.554K 次\u002F秒 | 8.563K 次\u002F秒 | 2.87 倍 |\n| B=64，1024 宽度隐藏层 + 5 次逐点运算 | 2.716K 次\u002F秒 | 0.969K 次\u002F秒 | 2.80 倍 |\n\n在 Nvidia GP100 上：\n\n| 基准测试     | Shumai (bun)  | TF.js (node)  | 差异 |\n| ------------- |---------------| --------------| -----------|\n| 32 宽度加法 | 243.217K 次\u002F秒 | 34.539K 次\u002F秒 | 7.04 倍 |\n| 1024 宽度加法 | 144.771K 次\u002F秒 | 18.006K 次\u002F秒 | 8.04 倍 |\n| 32768 宽度加法 | 71.793K 次\u002F秒 | 17.071K 次\u002F秒 | 4.21 倍 |\n| 64×64 方阵乘法 | 63.239 GFlop\u002Fs | 12.749 GFlop\u002Fs | 4.96 倍 |\n| 128×128 方阵乘法 | 435.565 GFlop\u002Fs | 104.885 GFlop\u002Fs | 4.15 倍 |\n| 1024×1024 方阵乘法 | 7,165.062 GFlop\u002Fs | 6,470.793 GFlop\u002Fs | 1.11 倍 |\n| B=64，64 宽度隐藏层 + 5 次逐点运算 | 25.507K 次\u002F秒 | 5.192K 次\u002F秒 | 4.91 倍 |\n| B=64，128 宽度隐藏层 + 5 次逐点运算 | 22.529K 次\u002F秒 | 4.861K 次\u002F秒 | 4.63 倍 |\n| B=64，1024 宽度隐藏层 + 5 次逐点运算 | 11.568K 次\u002F秒 | 2.854K 次\u002F秒 | 4.05 倍 |\n\n\n## 内存使用\n\n虽然开箱即用的内存管理在许多情况下已经足够，但通过调整内存使用策略，可以显著减少垃圾回收器带来的额外开销，从而提升性能。\n\n```\nimport { util } from '@shumai\u002Fshumai'\n\nutil.memoryOptions({\n  lowerBoundThreshold: 100e6, \u002F\u002F 100MB\n  upperBoundThreshold: 5e9, \u002F\u002F 5GB\n  delayBetweenGCs: 1000 \u002F\u002F 1 秒\n})\n```\n\n请特别注意 `upperBoundThreshold` 参数：一旦超过该阈值，每次分配张量时都会强制触发垃圾回收，此时 `delayBetweenGCs` 将被忽略。合理设置该参数以充分利用硬件资源，可以显著提升性能。\n\n## 统计信息\n\n```mermaid\ngraph TD\n  OpA(操作A) --> statsA{{\"统计A\"}};\n  OpB(操作B) --> statsA;\n  statsA --> LoggerA{{\"LoggerConsole A\"}};\n  LoggerA --> Stdout((\"标准输出\"));\n  OpC(操作C) --> statsA;\n  OpD(操作D) --> statsA;\n  statsA --> LoggerB(\"自定义日志记录器B\");\n  LoggerB --> Disk((\"磁盘\"));\n```\n\n收集统计信息的基本用法非常简单，只需使用默认的 `StatsLoggerConsole` 添加一个收集器即可。\n\n```javascript\nimport { stats, StatsLoggerConsole, rand, matmul } from '@shumai\u002Fshumai'\n\nstats.enabled = true \u002F\u002F 之后的所有操作都会捕获统计信息\n\n\u002F\u002F 执行操作...\n\nstats.enabled = false \u002F\u002F 之后的所有操作将不再捕获统计信息\n```\n\n虽然上述示例对于简单的使用场景已经足够，但如果你希望在多个线程、进程和\u002F或主机上捕获统计信息，`StatsLoggerHttp` 将能满足你的需求。\n\n```mermaid\ngraph TD\n  subgraph 主机C\n    Processor(\"Http日志处理器\")\n    style Processor stroke:#222,stroke-width:4px,stroke-dasharray:5 5\n  end\n  subgraph 主机A\n    OpA(操作A) --> statsA{{\"统计A\"}};\n    OpB(操作B) --> statsA;\n    statsA --> LoggerA{{\"Http日志记录器A\"}};\n    LoggerA --> Processor;\n  end\n  subgraph 主机B\n    OpC(操作C) --> statsB{{\"统计B\"}};\n    OpD(操作D) --> statsB;\n    statsB --> LoggerB{{\"Http日志记录器B\"}};\n    LoggerB --> Processor;\n  end\n```\n\n```javascript\nimport { StatsLoggerHttp } from '@shumai\u002Fshumai'\n\nstats.logger = new StatsLoggerHttp({ url: 'http:\u002F\u002Flocalhost:4242' })\n```\n\n对于更定制化的需求，你可以提供自己的日志记录器：\n\n```javascript\nimport { StatsLogger, StatsLoggerData } from '@shumai\u002Fshumai'\n\nclass CustomLogger implements StatsLogger {\n  async process(data: StatsLoggerData): Promise\u003Cvoid> {\n    const summary = data.collector.getSummary()\n    console.log('收集器统计信息:', summary)\n  }\n}\n\nstats.logger = new CustomLogger()\n```\n\n默认情况下，堆栈跟踪功能是禁用的，因为它会增加 50% 以上的开销。不过，可以通过设置 `stats.collectStacks = true` 来启用它。\n\n### 作用域内的统计信息\n\n如果你希望隔离统计分析，也可以这样做：\n\n```javascript\nimport { collectStats } from '@shumai\u002Fshumai'\n\nconst scopedStats = collectStats(() => {\n  \u002F\u002F 执行操作...\n}\u002F*, StatsCollectorOptions | StatsLogger *\u002F)\nconsole.log(scopedStats.getSummary())\n```\n\n\n## 贡献\n\n如果你想对核心绑定或 FFI 进行修改，请先从[源代码构建](#从源代码安装)。\n\n所有以 `*.inl` 或 `*_gen.ts` 结尾的文件都是生成的。这些文件可以通过编辑 [`scripts\u002Fgen_binding.py`](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fblob\u002Fmain\u002Fscripts\u002Fgen_binding.py) 并运行 [`.\u002Fscripts\u002Fgen_all_binding.sh`](https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fblob\u002Fmain\u002Fscripts\u002Fgen_all_binding.sh) 来修改。\n\n有关风格指南及如何参与贡献的更多信息，请参阅 [CONTRIBUTING](CONTRIBUTING.md) 文件。 😁\n\n### 许可证\n\nshumai 采用 MIT 许可证，具体内容请参见 LICENSE 文件。","# Shumai 快速上手指南\n\nShumai 是一个基于 TypeScript\u002FJavaScript 的高性能、可微分张量库，专为软件工程师和研究人员设计。它利用 [Bun](https:\u002F\u002Fbun.sh) 运行时和 [Flashlight](https:\u002F\u002Fgithub.com\u002Fflashlight\u002Fflashlight) 后端，提供快速的网络连通性和 GPU 加速能力。\n\n> ⚠️ **注意**：本项目目前处于实验阶段，主要支持 macOS 和 Linux 系统。\n\n## 1. 环境准备\n\n在开始之前，请确保你的系统满足以下要求：\n\n*   **操作系统**：macOS 或 Linux (Windows 用户建议通过 WSL2 + Docker 使用)。\n*   **运行时**：必须安装 [Bun](https:\u002F\u002Fbun.sh)。\n*   **底层依赖**：必须安装 [ArrayFire](https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire)。\n    *   **macOS**：默认使用 CPU 后端。\n    *   **Linux**：默认推荐使用 CUDA 后端（需 NVIDIA GPU），也可构建 CPU 后端。\n\n### 安装前置依赖\n\n#### macOS 用户\n使用 Homebrew 一键安装 ArrayFire：\n```bash\ncurl https:\u002F\u002Fbun.sh\u002Finstall | bash\nbrew install arrayfire\n```\n\n#### Linux 用户 (Ubuntu x86-64)\n使用官方源安装 ArrayFire (CPU\u002FOpenBLAS 版本)：\n```bash\ncurl https:\u002F\u002Fbun.sh\u002Finstall | bash\nsudo apt install -y gnupg2 ca-certificates\nsudo apt-key adv --fetch-key https:\u002F\u002Frepo.arrayfire.com\u002FGPG-PUB-KEY-ARRAYFIRE-2020.PUB\necho \"deb https:\u002F\u002Frepo.arrayfire.com\u002Fdebian all main\" | sudo tee \u002Fetc\u002Fapt\u002Fsources.list.d\u002Farrayfire.list\nsudo apt update\nsudo apt install -y arrayfire-cpu3-dev arrayfire-cpu3-openblas\n```\n*注：若需使用 GPU 加速，请参考 ArrayFire 官方文档安装 CUDA 版本。*\n\n#### Linux 用户 (Ubuntu ARMv8)\n需要从源码编译 ArrayFire：\n```bash\ncurl https:\u002F\u002Fbun.sh\u002Finstall | bash\nsudo apt remove libarrayfire-dev libarrayfire-cpu3 libarrayfire-cpu-dev\nsudo apt install -y libblas-dev liblapack-dev liblapacke-dev libfftw3-dev libboost-all-dev cmake make g++\ncd \u002Ftmp\nsudo rm -rf arrayfire\ngit clone https:\u002F\u002Fgithub.com\u002Farrayfire\u002Farrayfire.git\ncd arrayfire\ncmake -Bbuild -DAF_BUILD_EXAMPLES=OFF -DCMAKE_BUILD_TYPE=Release -DAF_BUILD_UNIFIED=OFF -DAF_TEST_WITH_MTX_FILES=OFF -DBUILD_TESTING=OFF\nmake -j4 -Cbuild\nsudo make install -Cbuild\n```\n\n## 2. 安装步骤\n\n完成上述依赖安装后，使用 Bun 安装 Shumai：\n\n```bash\nbun install @shumai\u002Fshumai\n```\n\n> **提示**：如果安装过程中遇到问题，由于安装流程仍在完善中，建议在 GitHub 仓库提交 Issue 并附上你的平台信息。\n\n## 3. 基本使用\n\nShumai 会自动检测并使用连接的 GPU 或加速器；若无可用设备，将回退到 ArrayFire CPU 后端。\n\n### 创建张量与矩阵运算\n```javascript\nimport * as sm from \"@shumai\u002Fshumai\"\n\n\u002F\u002F 创建一个 1024x1024 的张量，填充正态分布随机数\nlet X = sm.randn([1024, 1024])\nlet W = sm.identity(1024)\n\n\u002F\u002F 矩阵乘法\nlet Y = X.matmul(W)\n\nconsole.log(Y.shape)\n```\n\n### 与原生 JavaScript 数组互转\n```javascript\n\u002F\u002F 原生 JS 数组 -> Shumai Tensor\nconst data = new Float32Array(128)\nfor (let i = 0; i \u003C 128; ++i) {\n  data[i] = Math.random()\n}\n\nconst X = sm.tensor(data)\nconst pi = sm.scalar(3.14)\nconst Y = X.mul(pi)\n\n\u002F\u002F Shumai Tensor -> 原生 JS 数组\nconst Y_data = Y.toFloat32Array()\n\n\u002F\u002F 标量张量 -> JS Number\nconst total = X.sum().toFloat32()\n```\n\n### 自动求导 (Gradients)\n```javascript\nconst W = sm.randn([128, 128])\nW.requires_grad = true \u002F\u002F 开启梯度追踪\n\nconst X = sm.randn([128, 128])\nconst diff = X.sub(W)\nconst mse = diff.mul(diff).sum()\n\nmse.backward() \u002F\u002F 反向传播\n\nconsole.log(W.grad) \u002F\u002F 梯度已计算并存入 .grad\n\n\u002F\u002F 停止梯度追踪\nconst Y = W.detach()\nY.sum().backward() \u002F\u002F 不会改变 W 的梯度\n```","一位全栈工程师正在为电商网站开发实时的“个性化商品推荐”功能，需要在 Node.js 环境中直接运行深度学习模型进行推理。\n\n### 没有 shumai 时\n- **架构割裂严重**：前端或后端逻辑使用 TypeScript 编写，而模型推理必须调用独立的 Python 服务，导致系统需要维护两套运行时环境，部署复杂度极高。\n- **通信延迟高昂**：Node.js 服务与 Python 推理服务之间需通过 HTTP 或 gRPC 传递大量张量数据，网络序列化与反序列化过程引入了显著的毫秒级延迟，无法满足实时交互需求。\n- **开发体验断层**：算法工程师优化的模型难以直接复用于工程代码，类型系统不互通，调试时需要同时在两个语言生态中切换，极易出错且效率低下。\n- **资源利用率低**：为了维持双服务架构，服务器必须同时加载 Node.js 和 Python 的解释器及依赖库，内存占用翻倍，增加了云成本。\n\n### 使用 shumai 后\n- **原生统一运行**：借助 Bun 运行时，shumai 让开发者直接在 TypeScript 代码中导入并执行高性能张量运算，彻底消除了对独立 Python 推理服务的依赖。\n- **零拷贝极速推理**：利用底层 Flashlight 和 ArrayFire 的加速能力，数据在内存中直接处理，避免了跨进程\u002F跨语言的网络传输开销，将推荐响应时间从百毫秒级降低至毫秒级。\n- **端到端类型安全**：整个数据流转过程（从用户请求到模型输出）均保持在 TypeScript 类型系统内，享受完整的智能提示与编译期检查，大幅提升了代码可维护性。\n- **轻量化部署**：单一二进制文件即可包含业务逻辑与 AI 能力，显著减少了容器镜像体积和服务器内存占用，使得边缘计算或 Serverless 部署变得轻而易举。\n\nshumai 打破了 JavaScript 生态与高性能 AI 计算之间的壁垒，让全栈开发者能在一个统一的类型安全环境中构建真正的实时智能应用。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffacebookresearch_shumai_ef53796f.png","facebookresearch","Meta Research","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Ffacebookresearch_449342bd.png","",null,"https:\u002F\u002Fopensource.fb.com","https:\u002F\u002Fgithub.com\u002Ffacebookresearch",[81,85,89,93,97,101],{"name":82,"color":83,"percentage":84},"TypeScript","#3178c6",81.7,{"name":86,"color":87,"percentage":88},"C++","#f34b7d",13.9,{"name":90,"color":91,"percentage":92},"Python","#3572A5",3.7,{"name":94,"color":95,"percentage":96},"Shell","#89e051",0.4,{"name":98,"color":99,"percentage":100},"JavaScript","#f1e05a",0.2,{"name":102,"color":103,"percentage":104},"CMake","#DA3434",0.1,1171,26,"2026-04-10T19:12:32","MIT",4,"Linux, macOS","Linux 默认使用 CUDA 后端（需 NVIDIA GPU），macOS 默认使用 CPU 后端。未明确指定具体显卡型号、显存大小或 CUDA 版本要求，但需安装支持 CUDA 的 ArrayFire。","未说明",{"notes":114,"python":115,"dependencies":116},"1. Windows 非官方支持，但可通过 WSL2 + Docker + Linux 运行（含 CUDA 支持）。2. macOS 用户建议通过 Homebrew 安装 ArrayFire CPU 后端。3. Linux 用户（x86-64）可 apt 安装 ArrayFire，ARMv8 架构需从源码编译。4. 该工具处于实验阶段，安装过程仍在完善中。5. 若从源码构建，需手动编译 Flashlight 及其绑定库。","不需要 (基于 TypeScript\u002FJavaScript)",[117,118,119],"bun","arrayfire","flashlight",[14],"2026-03-27T02:49:30.150509","2026-04-16T02:02:36.295735",[124,129,134,139,144],{"id":125,"question_zh":126,"answer_zh":127,"source_url":128},35084,"如何在 Linux ARM64 架构上运行 Shumai？","由于 ArrayFire 官方未提供 Linux ARM64 的二进制文件，您需要手动构建并安装。请运行以下脚本，它会自动从源码构建 ArrayFire 并安装 Flashlight 绑定：\n\n```bash\ncurl -L -O https:\u002F\u002Fraw.githubusercontent.com\u002Ffacebookresearch\u002Fshumai\u002Fmain\u002F.github\u002Fscripts\u002Finstall_arrayfire-shumai-flashlight-linux-arm64-cpu.sh\nbash install_arrayfire-shumai-flashlight-linux-arm64-cpu.sh\n```\n\n注意：早期版本可能需要手动重命名 CPU 后端包，但最新脚本已处理此问题。如果脚本需要改进，社区欢迎贡献针对 ARM64 的构建脚本。","https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fissues\u002F53",{"id":130,"question_zh":131,"answer_zh":132,"source_url":133},35085,"运行示例代码（如 bench.ts）时出现段错误（Segmentation Fault）怎么办？","这通常是由于使用的 Bun 版本过旧导致的已知问题。该问题已在 Bun 的后续提交中修复。\n\n解决方法是升级到 Bun 的 Canary 版本：\n```bash\nbun upgrade --canary\n```\n\n如果问题仍然存在，可能是垃圾回收（GC）期间发生的崩溃，建议检查是否使用了最新的 Shumai 代码库，因为维护者已添加了一些调试信息来追踪此类问题。","https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fissues\u002F49",{"id":135,"question_zh":136,"answer_zh":137,"source_url":138},35086,"反向传播训练过程中速度极慢（高达 60 倍延迟）是什么原因？","这是因为在反向传播期间频繁调用 `tensor.update()` 触发了过多的垃圾回收（GC），严重影响了性能。\n\n临时解决方案是修改 GC 触发逻辑，避免在紧密循环中频繁执行 GC。可以设置内存使用的上下限阈值，仅在必要时触发 GC。例如：\n\n```typescript\n\u002F\u002F util\u002Fgc.ts\nlet delayBetweenGCs = 1000;\nlet nextGC = Date.now() + delayBetweenGCs;\nlet lowerBoundThreshold = 100e6; \u002F\u002F 100MB\nlet upperBoundThreshold = 5e9; \u002F\u002F 5GB\n\nexport function gcAsNeeded() {\n  const bytesUsed = fl.bytesUsed.native();\n  const now = Date.now();\n  if ((bytesUsed >= upperBoundThreshold) || (now >= nextGC && bytesUsed >= lowerBoundThreshold)) {\n    Bun.gc(true);\n    nextGC = now + delayBetweenGCs;\n  }\n}\n```\n\n建议在 Tensor 构造函数中调用此函数，以便所有代码路径受益。","https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fissues\u002F125",{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},35087,"Shumai 是否支持 Float16Array？性能如何？","JavaScript 原生不支持 `Float16Array`。虽然可以使用 `@petamoriken\u002Ffloat16` 库来实现，但性能测试表明其存在显著开销：\n\n1. 创建数组时：`Float16Array` 比 `Float32Array` 慢约 27%（测试数据：3.74秒 vs 2.94秒）。\n2. 遍历和更新数值时性能差距更大。\n\n维护者认为在 JS 层面模拟 FP16 价值不大。推荐的方案是创建一个作为 `Float32Array` 别名的 `Float16Array`，仅用于类型推断和将 f16 传递给原生层，而不实际在 JS 中进行半精度计算。","https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fissues\u002F54",{"id":145,"question_zh":146,"answer_zh":147,"source_url":148},35088,"为什么项目选择实现自定义操作（custom ops）而不是直接绑定 Flashlight 的变量函数？","虽然直接绑定 Flashlight 的底层函数（如 softmax 或激活函数）可以减少 FFI 调用次数，但项目目前倾向于通过自定义操作（custom ops）来实现。这种模式允许更灵活地控制张量操作逻辑，并更好地适应 JavaScript\u002FTypeScript 的运行环境。如果您有具体的绑定需求或更好的实现模式，欢迎在 Issue 中进一步讨论或提交 PR。","https:\u002F\u002Fgithub.com\u002Ffacebookresearch\u002Fshumai\u002Fissues\u002F83",[]]