fandhe-ai

Rust 製 AI/ML ライブラリです。Burn 等の既存フレームワークに依存せず、テンソル・ autodiff・演算グラフ／カーネル融合機構・計算カーネル・バックエンド抽象層を 完全自作コアとして実装しています。

A from-scratch Rust AI/ML library — no Burn/candle/tch dependency. See the Getting Started section below for install & a minimal example.

ドキュメント

利用者向けドキュメントサイト（GitHub Pages）は公開済みです。

• https://fandhe-ai.github.io/fandhe-ai/

ローカルでビルドして確認する場合は次のコマンドを実行してください。

cargo run -p docs-site -- --out dist/

生成物は dist/index.html から閲覧できます。ビルドには内部リンク検証（linkcheck）が 内蔵されており、リンク切れを検出した場合は非 0 終了します。コンテンツの正は site/ 配下、サイト構成は site/nav.toml です。

インストール

本ライブラリは Rust の stable チャンネルを前提としています（リポジトリ直下の rust-toolchain.toml が単一真実源です）。crates.io（v0.14.0・ 2026-11-05 公開済み）から利用できます。

[dependencies]
fandhe-ai = "0.14.0"

公開ドキュメントは以下のとおりです。

• https://docs.rs/fandhe-ai

開発版を試す場合は Git 依存で参照できます。

[dependencies]
fandhe-ai = { git = "https://github.com/Fandhe-AI/fandhe-ai" }

利用者が直接依存すべきクレートは fandhe-ai だけです。fandhe-ai-tensor-core・ fandhe-ai-autodiff・fandhe-ai-backend-cpu・fandhe-ai-backend-cuda・ fandhe-ai-backend-metal は内部クレートであり、直接の依存・利用はサポート対象外 です（下記「クレート構成」参照）。

最小コード例

compat::array（numpy np.array 慣習のテンソル生成）と compat::Sequential （Keras Sequential 慣習のレイヤー積み上げ）を使うと、数行でモデルを組み立てて 推論できます。以下は crates/facade/examples/getting_started.rs （cargo run -p fandhe-ai --example getting_started で実行確認済み）と同一のコードです。

use fandhe_ai::compat::{Sequential, array};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = array(vec![
        vec![0.1_f32, 0.2, 0.3, 0.4],
        vec![0.5_f32, 0.6, 0.7, 0.8],
    ])?;

    let model = Sequential::new()
        .add_linear(4, 8, /* seed = */ 42)?
        .add_relu()
        .add_linear(8, 2, /* seed = */ 43)?;

    let output = model.predict(&input)?;

    println!("output shape: {:?}", output.shape());
    Ok(())
}

実行コマンドと期待出力:

cargo run -p fandhe-ai --example getting_started
# => output shape: [2, 2]

クレート構成とサポート境界

内部は複数のクレートに分かれていますが、利用者が直接触れるのは fandhe-ai クレートだけです。

クレート	役割
fandhe-ai	唯一のサポートされる公開 API 面。composition root（tape()／tape_for(Device)）・compat 公開面（compat::array／compat::Sequential）・optim（Sgd／AdamW 等）・デバイス常駐更新経路（DeviceParamStore／Tape::step_device_param_store）の 4 つを確定入口として提供します（docs/compat-api-scope.md §0）
fandhe-ai-tensor-core・fandhe-ai-autodiff・fandhe-ai-backend-cpu・fandhe-ai-backend-cuda・fandhe-ai-backend-metal	内部クレート。直接利用はサポート対象外です

上記 6 クレートと、下記の fandhe-ai-onnx-interop・fandhe-ai-hf-hub・fandhe-ai-backend-rocm の計 9 クレートを crates.io に公開しています（docs/crates-io-naming-decision.md）。 fandhe-ai-hf-hub・fandhe-ai-backend-rocm は v0.14.0（2026-11-05）で初回公開しました。 ディレクトリ名（crates/tensor-core 等）はリネーム前のまま維持しており、 [package] name（crates.io 公開名）のみ fandhe-ai prefix 付きへ変更しています。 相互運用（ONNX／safetensors）を担う fandhe-ai-onnx-interop（crates/onnx-interop）は v0.10.0（2026-10-03）から 7 クレート目として crates.io に公開しています。 ONNX import／export は fandhe_ai::interop::onnx（OnnxModel／ OnnxValue／OnnxError・OnnxModel::{from_bytes, from_path, run, to_bytes, to_path}・OnnxExportOptions）として fandhe-ai から公開済み です（export は import 済みモデルの roundtrip 限定）。safetensors save／load は引き続き fandhe-ai からの再エクスポートが未提供のため 利用できません。

このほか、自己修復ループ（guardrail・self-repair）・ベンチ計測（bench-harness）・ ドキュメントサイト生成（docs-site）や HF Hub 連携の補助（hf-hub。v0.14.0 で crates.io へ初回公開）・ROCm バックエンドの雛形（backend-rocm。HIP を実行時に動的ロードする。v0.14.0 で crates.io へ初回公開。ROCm 実機 parity は未実測のまま所有者判断で公開）を担う内部クレートがあります。 compat API のサポート境界の詳細は docs/compat-api-scope.md を参照してください。

バックエンド

バックエンド切替は feature フラグを使わない cfg ベースです。CPU は常に利用 可能な既定バックエンドで、CUDA・Metal は実行時にデバイスの存在を検証し、利用 できない場合はエラーを返します（自動フォールバックはしません）。バックエンド 間の数値一致は「相対誤差 1e-3 未満または絶対誤差 1e-5 未満」の複合判定で担保 します（詳細 → docs/backend-switching-design.md）。

Metal バインディングは objc2-metal 直接（wgpu 不採用: 直接比 約 2.3 倍実測・ PoC-v2-4。詳細 → docs/backend-metal-wgpu-decision.md）。

ステータス

• crates.io 公開済み: 初回公開 v0.3.0（6 クレート: fandhe-ai・ fandhe-ai-tensor-core・fandhe-ai-autodiff・fandhe-ai-backend-cpu・ fandhe-ai-backend-cuda・fandhe-ai-backend-metal）を 2026-08-23 に、 最新 v0.14.0（9 クレート。fandhe-ai-hf-hub・fandhe-ai-backend-rocm は初回公開）を 2026-11-05 に公開済み（公開履歴の正は docs/crates-io-publishing-order.md §10）
• ドキュメントサイト公開済み: https://fandhe-ai.github.io/fandhe-ai/
• 実装の進行状況: コア（テンソル・autodiff・演算グラフ／カーネル融合機構）・ 3 バックエンド（CPU／CUDA／Metal）の実装と性能実測を継続中

開発（コントリビュータ向け）

以下はライブラリを clone してコントリビュートする開発者向けの情報です（利用者は上記の 「インストール」「最小コード例」だけで十分です）。

• 依存は許容 12 区分のみを =x.y.z 完全固定で管理する。本体 workspace の直接依存として許容するのは第 1〜8 区分・第 10〜12 区分の 11 区分で、うち第 1〜8 区分（cudarc／objc2 系／safetensors／prost／serde 系／rayon／half／criterion）は本体 workspace ルート Cargo.toml の [workspace.dependencies] に一元定義済み。第 10 区分の libc〈cfg(unix) 限定〉は本体 workspace の直接依存として追加する場合も同じくルート Cargo.toml で完全固定する（実追加は PR #2348。用途は facade のキャッシュ書き込みへも拡張〈#3124〉）。第 11 区分の ureq〈native-tls＋vendored・cfg(unix) 限定・HTTPS 取得用途限定。#3124〉もルート Cargo.toml で完全固定する。第 12 区分の libloading〈HIP／HIPRTC の動的ロード用途限定・backend-rocm のみ・無条件依存。#3154〉もルート Cargo.toml で完全固定する。第 9 区分（matrixmultiply／gemm。OSS GEMM ベンチ比較対象）は scripts/bench/oss-gemm-compare/（独立 Cargo プロジェクト）限定で本体 workspace への混入を禁止する（詳細 → .claude/rules/deps-policy.md）
• 依存禁止リスト（burn 系一式・cubecl・candle・tch・ndarray）を CI で機械検査

依存追加・更新フロー

依存の追加・更新は必ずユーザー承認を経て行う（.claude/rules/deps-policy.md）。承認後の実施手順:

This is the beginning of the README. Read the rest at the original. Read the full README ↗