granite-embedding-97m-multilingual-r2-ONNX

ibm-granite/granite-embedding-97m-multilingual-r2 を ONNX に変換し、ブラウザ／Node.js（Transformers.js）や ONNX Runtime から利用できるようにしたものです。

This is an ONNX conversion of IBM's granite-embedding-97m-multilingual-r2 sentence-embedding model, packaged for use with Transformers.js and ONNX Runtime.

来歴 / Provenance

項目	内容
オリジナルモデル	ibm-granite/granite-embedding-97m-multilingual-r2（IBM Granite Team）
アーキテクチャ	ModernBERT, hidden size 384, 約 97M パラメータ, 最大 32,768 トークン
埋め込み次元	384
プーリング	CLS トークン + L2 正規化（normalize）
変換者	@yuiseki
変換内容	PyTorch (safetensors) → ONNX (fp32) + 量子化バリアント

本リポジトリはオリジナルの重みを ONNX 形式へ変換しただけの派生物であり、モデルそのものを再学習・改変したものではありません。モデルの性能・対応言語・利用上の注意点については、必ずオリジナルのモデルカードを参照してください。

ライセンス / License

オリジナルと同じく Apache License 2.0 で配布します。

This conversion is distributed under the Apache License 2.0, the same license as the original model. The original model is Copyright IBM Corp. See the bundled LICENSE file for the full license text. This repository only re-packages the original weights into ONNX format and does not alter the model itself.

同梱ファイル / Available files

onnx/ 配下に fp32 と各種量子化バリアントを収録しています。括弧内は、オリジナル（sentence-transformers）の埋め込みに対する平均コサイン類似度（日英のサンプル文で計測）。

ファイル	精度	サイズ	対オリジナル cos
onnx/model.onnx	fp32	~372 MB	1.0000
onnx/model_fp16.onnx	fp16	~187 MB	1.0000
onnx/model_quantized.onnx	int8 (動的, 既定)	~94 MB	0.9551
onnx/model_int8.onnx	int8	~94 MB	0.9551
onnx/model_uint8.onnx	uint8	~94 MB	0.9629
onnx/model_q4.onnx	4-bit	~281 MB	0.9903
onnx/model_q4f16.onnx	4-bit + fp16	~148 MB	0.9903
onnx/model_bnb4.onnx	bitsandbytes 4-bit	~280 MB	0.9881

入力は input_ids と attention_mask、出力は last_hidden_state（shape (batch, seq_len, 384)）です。文ベクトルを得るには CLS トークン（先頭トークン）を取り出して L2 正規化してください。

補足: このモデル（ModernBERT 系）では int8 量子化の精度劣化がやや大きめ（cos ≈ 0.955）です。サイズと精度のバランスを取りたい場合は model_q4f16.onnx（4-bit + fp16, cos ≈ 0.99）が有力な選択肢です。

使い方 / Usage

Transformers.js

import { pipeline } from '@huggingface/transformers';

const extractor = await pipeline(
  'feature-extraction',
  'yuiseki/granite-embedding-97m-multilingual-r2-ONNX',
  // 量子化版を使う場合: { dtype: 'q4f16' } など
);

const output = await extractor(
  ['こんにちは、世界', 'How do I convert a model to ONNX?'],
  { pooling: 'cls', normalize: true },
);
console.log(output.tolist()); // [[...384 dims...], [...]]

Python (ONNX Runtime)

import numpy as np
import onnxruntime as ort
from transformers import AutoTokenizer
from huggingface_hub import hf_hub_download

repo = "yuiseki/granite-embedding-97m-multilingual-r2-ONNX"
tok = AutoTokenizer.from_pretrained(repo)
path = hf_hub_download(repo, "onnx/model.onnx")  # or model_q4f16.onnx
sess = ort.InferenceSession(path)

enc = tok(["こんにちは、世界", "東京は日本の首都です。"],
          padding=True, truncation=True, return_tensors="np")
feeds = {i.name: enc[i.name] for i in sess.get_inputs()}
last_hidden = sess.run(None, feeds)[0]            # (B, T, 384)

cls = last_hidden[:, 0]                            # CLS pooling
emb = cls / np.linalg.norm(cls, axis=-1, keepdims=True)  # L2 normalize
print(emb.shape)  # (2, 384)

変換プロセス / Conversion process

Transformers.js v3.7.1 の変換スクリプト（🤗 Optimum ベース）を使用しました。

python -m scripts.convert \
  --model_id ibm-granite/granite-embedding-97m-multilingual-r2 \
  --quantize \
  --task feature-extraction \
  --library_name transformers

--library_name transformers を指定することで、sentence-transformers ラッパー経由ではなく素の ModernBertModel（feature-extraction）として last_hidden_state を出力するエクスポートを行い、プーリング／正規化は呼び出し側に委ねる構成にしています。--quantize により fp16 / q8 / int8 / uint8 / q4 / q4f16 / bnb4 の各バリアントを生成しました。

変換環境 / Environment

torch==2.5.1
transformers==4.49.0
optimum==1.25.0.dev0   (git: huggingface/optimum@b04feaea)
onnx==1.17.0
onnxruntime==1.20.1
onnxslim==0.1.48

補足: ModernBERT は transformers>=4.48 と ModernBERT 対応版 Optimum が必要です。さらに torch 2.12 の新しい dynamo ベース ONNX exporter は Optimum の外部データ後処理（model.onnx.data の削除）と噛み合わず FileNotFoundError で失敗するため、旧来の torch.onnx.export 経路を使う torch 2.5.1 に固定して回避しています。

検証 / Verification

fp32 出力は Optimum のエクスポート時検証で PyTorch 版と一致（atol 1e-4）。さらに sentence-transformers のオリジナル埋め込みと CLS プーリング後のコサイン類似度を比較し、全バリアントで上表の通りの一致を確認しています。

謝辞 / Acknowledgements

Original model by the IBM Granite Team. ONNX への変換・再公開のみを行いました。