fandhe-ai

A from-scratch Rust AI/ML library — no Burn/candle/tch dependency.

Rust 製 AI/ML ライブラリ fandhe-ai の composition root であり、唯一のサポートされる公開 API 面です。テンソル・autodiff・バックエンド抽象層を完全自作コアとして実装した内部クレート群（fandhe-ai-tensor-core・ fandhe-ai-autodiff・fandhe-ai-backend-cpu・fandhe-ai-backend-cuda・ fandhe-ai-backend-metal）を結線し、Device 指定によるバックエンド選択と compat 公開面（compat::array／compat::Sequential）・optimizer 公開面（optim::{Sgd, AdamW, clip_grad_norm, LrScheduler} 等）を提供します。

インストール

[dependencies]
fandhe-ai = "0.4.0"

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

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

ビルド要件

Linux では、HTTPS によるモデル取得に使う TLS 依存（ureq。cfg(unix) 限定・OpenSSL を静的に同梱）のため perl・make・C ツールチェーンが必要です（libssl-dev は不要）。

最小コード例

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]）。

バックエンド

バックエンド切替は feature フラグを使わない cfg ベースです。既定の fandhe_ai::tape() は常に利用可能な CPU バックエンドを結線し、Device::Cuda(_)／ Device::Metal を明示指定したい場合は fandhe_ai::tape_for(Device) を使います。 CUDA・Metal は実行時にデバイスの存在を検証し、利用できない場合はエラーを返します（自動フォールバックはしません）。バックエンド間の数値一致は「相対誤差 1e-3 未満または絶対誤差 1e-5 未満」の複合判定で担保します。

相互運用（interop）

fandhe_ai::interop::safetensors から safetensors 形式の save／load （compat::Sequential::state_dict／load_state_dict と組み合わせて使います）へ到達できます。NumPy 互換の .npy／.npz 読み書き（Tensor<f32> 限定のパス版 load_npy／save_npy／load_npz／save_npz と NpyError）は fandhe_ai::interop::npy から利用できます（書き出しは原子的ではなく、読み込みは symlink を辿ります。詳細はモジュール doc）。

use fandhe_ai::compat::Sequential;
use fandhe_ai::interop::safetensors::{
    load_safetensors_f32_from_bytes, save_safetensors_f32_to_bytes,
};

let model = Sequential::new().add_linear(4, 8, /* seed = */ 1).unwrap();
let bytes = save_safetensors_f32_to_bytes(&model.state_dict(), None).unwrap();
let loaded = load_safetensors_f32_from_bytes(&bytes).unwrap();

ONNX import（fandhe_ai::interop::onnx::OnnxModel）も利用できます（詳細は docs/facade-onnx-import-exposure-decision.md 参照）。ONNX export への再エクスポートは引き続き未提供です。

ローカルモデルレジストリ

fandhe_ai::model::ModelRegistry は $HOME/.fandhe-ai/models/<name>/<version>/model.safetensors （Windows は $USERPROFILE）というレイアウトを規定し、名前・バージョン指定での同期ロードを提供します（読み取り系は作成・削除をしません。 save（Linux x86_64／aarch64 限定）だけが書き込みます）。load／available_models の対応プラットフォームは Linux（x86_64／aarch64）・macOS 限定です。キャッシュルート解決（$USERPROFILE 優先）自体は Windows でも動作しますが、シンボリックリンク経由の脱出対策（no-follow オープン）が Linux／macOS 限定実装のため、Windows および上記以外のアーキテクチャでは fail-closed で非対応（load は常に Err、available_models は常に空の一覧）です。

use fandhe_ai::model::ModelRegistry;

let registry = ModelRegistry::new().unwrap();
let state_dict = registry.load("mlp", "v1").unwrap();
for (name, versions) in registry.available_models() {
    println!("{name}: {versions:?}");
}

ドキュメント・リポジトリ

利用者向けドキュメントサイト（GitHub Pages）: https://fandhe-ai.github.io/fandhe-ai/（Getting Started / Guides / Examples / API Reference）。API リファレンスは https://docs.rs/fandhe-ai

ソース: https://github.com/Fandhe-AI/fandhe-ai/tree/main/crates/facade
サポート境界の詳細: docs/compat-api-scope.md

ライセンス

MIT または Apache License 2.0（デュアルライセンス）。 LICENSE-MIT ／ LICENSE-APACHE

fandhe-ai 0.12.0