granite-embedding-278m-multilingual-ONNX

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

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

来歴 / Provenance

項目	内容
オリジナルモデル	ibm-granite/granite-embedding-278m-multilingual（IBM Granite Team）
アーキテクチャ	XLM-RoBERTa, hidden size 768, 約 278M パラメータ
埋め込み次元	768
プーリング	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	~1059 MB	1.0000
onnx/model_fp16.onnx	fp16	~530 MB	1.0000
onnx/model_quantized.onnx	int8 (動的, 既定)	~266 MB	0.9856
onnx/model_int8.onnx	int8	~266 MB	0.9856
onnx/model_uint8.onnx	uint8	~266 MB	0.9853
onnx/model_q4.onnx	4-bit	~786 MB	0.9941
onnx/model_q4f16.onnx	4-bit + fp16	~414 MB	0.9941
onnx/model_bnb4.onnx	bitsandbytes 4-bit	~781 MB	0.9944

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

使い方 / Usage

Transformers.js

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

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

const output = await extractor(
  ['こんにちは、世界', 'How do I convert a model to ONNX?'],
  { pooling: 'cls', normalize: true },
);
console.log(output.tolist()); // [[...768 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-278m-multilingual-ONNX"
tok = AutoTokenizer.from_pretrained(repo)
path = hf_hub_download(repo, "onnx/model.onnx")  # or model_quantized.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, 768)

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

変換プロセス / Conversion process

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

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

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

変換環境 / Environment

torch==2.4.1
transformers==4.43.4
optimum==1.21.3
onnx==1.16.2
onnxruntime==1.19.2
onnxconverter-common==1.14.0
onnxslim==0.1.31
protobuf==3.20.2

補足: 変換スクリプト同梱の requirements.txt は torch をピン留めしていないため、最新の torch 2.12 を入れると新しい ONNX exporter が onnxscript を要求し protobuf の依存が衝突します。旧来の torch.onnx.export 経路を使う torch 2.4.1 に固定し、onnx==1.16.2 / protobuf==3.20.2 を維持することで安定して変換できます。

検証 / Verification

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

謝辞 / Acknowledgements

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