Upload README.md with huggingface_hub

README.md

@@ -13,22 +13,29 @@ pipeline_tag: token-classification
 
 # bert-base-ner-mlx
 
+This is an unofficial [MLX](https://github.com/ml-explore/mlx) conversion of
+[dslim/bert-base-NER](https://huggingface.co/dslim/bert-base-NER) (a standard
+BERT-base with a named-entity-recognition head on top, trained on CoNLL-2003:
+PER/ORG/LOC/MISC). All credit for the original model goes to its author.
+
 [dslim/bert-base-NER](https://huggingface.co/dslim/bert-base-NER)（標準的なBERT-baseに
 固有表現抽出ヘッドを乗せたモデル。CoNLL-2003、PER/ORG/LOC/MISCの4種）の
 [MLX](https://github.com/ml-explore/mlx)版です。
 
-This is an unofficial MLX conversion of
-[dslim/bert-base-NER](https://huggingface.co/dslim/bert-base-NER).
-All credit for the original model goes to its author.
+## This cannot be loaded with mlx-embeddings / mlx-embeddingsでは読み込めません
 
-## これはmlx-embeddingsでは読み込めません
+`mlx-embeddings` targets pooled embedding/reranker outputs and doesn't
+support a per-token classification head. This model was **reimplemented from
+scratch for MLX** and requires the bundled `bert_ner_mlx.py`. The
+architecture itself is simple: a standard post-norm BERT encoder plus a
+linear classification head.
 
 `mlx-embeddings`はembedding/reranker用のpooling出力をターゲットにしており、トークン単位の
 分類ヘッド（各トークンに対して独立にラベルを出す構成）には対応していないため、**MLXでの
 実装をゼロから書き起こして**変換しています。同梱の`bert_ner_mlx.py`が必要です。構造自体は
 標準的なpost-norm BERTエンコーダー + 線形分類ヘッドとシンプルです。
 
-## 使い方
+## Usage / 使い方
 
 ```python
 import mlx.core as mx
@@ -55,17 +62,28 @@ for tok, label_id in zip(tokens, labels):
     print(tok, model.config.id2label[label_id] if hasattr(model, "config") else label_id)
 ```
 
+Labels are the same as the original model: `{0: "O", 1: "B-MISC", 2: "I-MISC",
+3: "B-PER", 4: "I-PER", 5: "B-ORG", 6: "I-ORG", 7: "B-LOC", 8: "I-LOC"}`.
+
 ラベルは元モデルと同じ: `{0: "O", 1: "B-MISC", 2: "I-MISC", 3: "B-PER", 4: "I-PER",
 5: "B-ORG", 6: "I-ORG", 7: "B-LOC", 8: "I-LOC"}`。
 
-## 精度検証
+## Accuracy / 精度検証
+
+Compared against the PyTorch fp32 reference on a real sentence containing
+person/location/organization entities:
 
 PyTorch fp32リファレンスと、実際の文章1件（人名・地名・組織名を含む）で比較:
 
-| 精度 | logitsコサイン類似度 | ラベル一致率 |
+| Precision / 精度 | Logits cosine sim. | Label agreement |
 |---|---|---|
 | MLX fp32 | 1.0 | 100% |
-| MLX fp16（本リリース） | 0.99999994 | 100% |
+| MLX fp16 (this release) | 0.99999994 | 100% |
+
+During fp16 conversion, using an attention-mask value like `-1e9` (which
+doesn't fit in fp16) caused `0 * (-inf) = NaN` at unmasked (`mask=1`)
+positions. Fixed by switching to `-1e4`, which fits fp16's range (full
+details are in the conversion-toolkit repo, not `SECURITY.md`).
 
 fp16変換の際、attention maskのマスク値に`-1e9`のようなfp16で表現できない大きな負数を使うと、
 マスクされていない（`mask=1`）位置で`0 * (-inf)`が発生してNaNになる罠があった。
@@ -76,13 +94,13 @@ fp16の範囲内に収まる`-1e4`に変更して解消している（詳細は`
 
 | Item | Value |
 |---|---|
-| Base model | `dslim/bert-base-NER`（BERT-base、108M params） |
+| Base model | `dslim/bert-base-NER` (BERT-base, 108M params) |
 | Precision | float16 |
-| Framework | MLX（`bert_ner_mlx.py`によるゼロからの実装） |
+| Framework | MLX (from-scratch `bert_ner_mlx.py`) |
 
 ## Notes
 
 - This is a community conversion, not an official release from the original author.
 - 本変換は非公式のコミュニティ版です。
-- セキュリティー監査には[model-audit-lite](https://github.com/masahirocom/model-audit-lite)を
-  使用しています（詳細は`SECURITY.md`）。
+- Security audit uses [model-audit-lite](https://github.com/masahirocom/model-audit-lite)
+  (see `SECURITY.md` for details).