deberta-v2-tiny-japanese-ime

DeBERTa Japanese IME reranker

A local, fail-closed reranker for finite Japanese IME candidate lists. It does not freely generate Japanese text or bundle model weights. Typo rescue enumerates a bounded set of roman-key hypotheses, and reported reranking accuracy remains conditional on the correct surface already being present in the candidate pool.

v0.11 は公開ブラウザー版の有限候補選択を堅牢化しました。DeBERTa/LFM Worker の応答を 共通 adapter で実行時検証し、候補数と同数の有限 score 以外は棄却します。表層候補は baseline との個別比較ではなく、全候補を一つの changed-span 文脈窓で一度だけ比較します。 同じ providerText へ正規化される異なる表示経路も捨てません。評価 CLI は候補生成 miss と 選択 error を分離し、artifact が宣言した provenance / reason / margin を別集計します。

既存 IME が出した有限個のかな漢字候補を、 ku-nlp/deberta-v2-tiny-japanese の文脈スコアで並べ替えるローカル Python パッケージです。候補を自由生成せず、 低信頼・モデル欠落・不正入力では既存順位をそのまま返します。

v0.6 は、QWERTY物理キーの近さを使うローマ字誤入力救済を主画面へ追加しました。 ローマ字として壊れた箇所、またはMozc語彙で未知に近い単語だけを対象に、置換・欠落・重複・ 隣接転置を最大2編集まで有限列挙します。各ローマ字候補をWindows IME best-oneへ変換し、 Mozc語彙costとDeBERTaの変更span文脈scoreを合わせ、改善量とmarginが両方十分な場合だけ採用します。 候補生成失敗、モデル例外、低信頼、文字種不正では元のWindows結果または英字入力を保持します。 watshi、watashu、hsshi、2箇所同時の watadhi ... toukyiu を実機で確認しています。

v0.5 は、ローカル診断UIの主画面を「英字のローマ字文を入力して Enter 1回」にしました。 このPCに入っている Windows 日本語IMEの IFELanguage best-one を、追加ライブラリや コンパイラなしのPython ctypes 経路から呼びます。空白区切りの自然な wa/e/o は IME式の ha/he/wo に整え、大文字・全角英字も正規化します。変換器を利用できない場合や 日本語結果が返らない場合は入力を保持し、かな入力のDeBERTa/Mozc診断は上級者向け画面へ 残しました。

v0.4 は、固定Mozc辞書top-8と実モデルをブラウザで試すローカル診断UIを追加しました。 期待表記を任意入力すると、候補生成、候補内順位、confidence gate、tokenizer/input境界を 分けて表示します。UI callback用にread-only Mozc indexのthread-safe lookupも追加しました。 入力は外部送信・自動保存せず、v0.2の精度値や凍結済みprofileは変更していません。

v0.3 は、既存アプリとモデルを分離する persistent local sidecar を追加しました。UTF-8 JSONL、request ID、明示 warmup、request timeout、子process再起動を提供し、timeout、crash、 壊れた応答、ID不一致、不正順位ではホストが渡した候補objectを元の順で返します。候補source IDとrevisionが校正済みMozc辞書cost profileに完全一致しない限り、モデルを呼びません。

v0.2 は、実際の表層読みと固定した Mozc OSS 辞書 top-8 を使い、UD Japanese-GSD dev だけで2つの安全 profile を調整しました。その後に初めて採点した UD Japanese-PUD 17,352件では、Mozc辞書cost順 88.27%から、増分向け左文脈のみで89.82%（+1.55pt）、 確定済み左右文脈で92.36%（+4.09pt）へ改善しました。改善/悪化はそれぞれ 441/172件、873/163件です。

これは「正解表記が top-8 に既にある」場合の条件付き reranking 精度です。top-8 candidate recall は88.28%で、候補missを誤りとした複数候補全体では、増分79.30%、 双方向81.54%です。Mozc OSS辞書の単語costだけを使う再現baselineであり、Mozc本体の Viterbi、接続cost、ユーザー学習、Google日本語入力の精度ではありません。詳細は outputs/benchmark_v02_pud_incremental.md と outputs/benchmark_v02_pud_bidirectional.md にあります。

Windows 11 の既存 Microsoft 日本語 IME については、公式 IFELanguage/IMM 経路を 実機probeしました。v0.5の主画面は、そのうち実証できた全文best-oneだけを利用します。 次候補は E_NOCAND、IMM候補listは0 bytesだったため、Microsoft IMEの有限候補を取得した、 またはその候補をDeBERTaで再順位付けしたとは主張しません。詳細は docs/v03-provider-research.md にあります。

v0.6の誤字救済は、Microsoft IMEの次候補を取得する機能ではありません。物理キーから作った 有限のローマ字仮説ごとにbest-oneを取得し、その有限集合だけを比較する別経路です。

Hugging Face 配布先は limoXD/deberta-v2-tiny-japanese-ime です。リポジトリは公開され、認証なしで閲覧・取得できます。Hub への配置はパッケージ配布の 証拠であり、実IME精度の保証ではありません。また、独自コードの再利用ライセンスは未決定です。 公開閲覧だけで利用・改変・再配布を許諾するものではありません。詳細は PUBLICATION_NOTICE.md を参照してください。

既存 IME の候補列 + 既存 prior + 単語分割済み文脈
                         |
                         v
  DeBERTa: 候補部分だけの masked-LM pseudo-log-likelihood
                         |
                         v
        prior 混合 -> confidence gate -> 安全な候補順

5分で試す

前提は Windows、Python 3.11以上、uv です。初回だけ Hugging Face から固定 revision の tokenizer と重みを取得します。

uv sync --extra dev
$env:HF_HOME = "$PWD\work\cache\huggingface"
uv run deberta-ime rerank `
  --input .\examples\rerank_requests.jsonl `
  --output .\work\demo_response.jsonl `
  --cache-dir .\work\cache\huggingface\hub
Get-Content .\work\demo_response.jsonl -Encoding UTF8

2回目以降は --offline を付ければ、キャッシュ以外へアクセスしません。 --input/--output は常に UTF-8 として扱うため、Windows PowerShell のパイプ時の コードページ差を避けられます。標準入出力の JSON Lines も利用できます。

ブラウザで試す（ローカル・入力保存なし）

このリポジトリにMozc indexと固定モデルcacheがある場合は、ローマ字全文変換、誤字救済、診断画面を 起動できます。主画面では watashi wa toukyou ni ikimasu のように英字だけで入力し、 Enterを1回押します。空白は自動で取り除き、単独の助詞 wa/e/o はIME入力向けに整えます。 外来語の長音は ra-men のように - を使うと安定します。たとえば watshi wa toukyou ni ikimasu や kawa ni kakaru hsshi o wataru も、そのままEnterで試せます。

上級者向けのDeBERTa候補診断では、正解表記を任意入力すると、改善先を「候補漏れ」 「モデル順位」「confidence gate」「tokenizer / 入力範囲」に分けます。現在の評価条件に 合わせるため、左右文脈は 川 に 架かる のように単語間へ空白を入れると安定します。

uv sync --extra demo
uv run --extra demo python .\examples\local_demo.py `
  --index .\work\data\mozc-3f235b4eb6fc.sqlite3 `
  --model-cache-dir .\work\cache\huggingface\hub

表示された http://127.0.0.1:7860 を開きます。既定では固定revisionをローカルcache だけから読み、入力を外部へ送信・自動保存しません。通常文はWindows IME全文best-one、 誤字らしい文だけは有限のQWERTY候補、Windows best-one、Mozc語彙cost、DeBERTa文脈gateを 使います。上級者向け画面はMozc OSS辞書の単語top-8で、いずれもMicrosoft候補一覧ではありません。

ビルド済み wheel は outputs/dist/deberta_ime_reranker-0.7.0-py3-none-any.whl です。SHA-256 は outputs/SHA256SUMS.txt で検証できます。 テスト、再現ビルド、別環境での no-deps smoke は outputs/verification_v11.md に分離して記録しています。

Hugging Face から取得する

公開配布のため認証は不要です。Hugging Face のrate limitを緩和したい場合だけ、事前に hf auth login を利用してください。

hf download limoXD/deberta-v2-tiny-japanese-ime `
  --local-dir .\deberta-v2-tiny-japanese-ime
Set-Location .\deberta-v2-tiny-japanese-ime
uv sync
uv run deberta-ime rerank `
  --input .\examples\rerank_requests.jsonl `
  --output .\work\demo_response.jsonl

wheel だけを取得する場合:

hf download limoXD/deberta-v2-tiny-japanese-ime `
  outputs/dist/deberta_ime_reranker-0.7.0-py3-none-any.whl `
  --local-dir .\deberta-ime-wheel
uv pip install `
  .\deberta-ime-wheel\outputs\dist\deberta_ime_reranker-0.7.0-py3-none-any.whl

v0.3 local sidecar

常駐serverは health ではmodelを読み込まず、warmup だけが固定modelをloadします。 ホストは通常 request timeoutを短く、warmup timeoutを長く分けられます。

uv run deberta-ime serve `
  --cache-dir .\work\cache\huggingface\hub `
  --offline

実際のホスト接続では公開 SidecarClient を使います。shellを介さず子processを起動し、 返却rankを検証してから元のmetadata付きcandidate objectへ適用します。

import sys
from deberta_ime import CandidateSource, SidecarClient

source = CandidateSource(
    "mozc_oss_dictionary_cost_v1",
    "3f235b4eb6fcff7d14ef5f0fb8ee56de7ee4c732",
)
candidates = (
    {"surface": "箸", "prior_score": 0.0, "host_id": 10},
    {"surface": "橋", "prior_score": -0.3, "host_id": 11},
)
command = (
    sys.executable,
    "-m",
    "deberta_ime",
    "serve",
    "--offline",
    "--cache-dir",
    "work/cache/huggingface/hub",
)
with SidecarClient(command, request_timeout_seconds=0.5) as client:
    client.warmup(timeout_seconds=120.0)
    result = client.rerank(
        reading="はし",
        candidates=candidates,
        candidate_source=source,
        mode="bidirectional",
        left_context=("川", "に", "架かる"),
        right_context=("を", "渡る"),
    )

このsource IDは固定 Mozc OSS辞書revisionの -(cost-best_cost)/1000 尺度だけを意味します。Microsoft IME表示順位、実Mozc converter、 Google Input Tools、全候補prior 0へ偽装して流用しないでください。未知sourceは reason=uncalibrated_source で元順位です。protocolとprocess failureの全規約は docs/spec-v03.md と docs/ime-integration.md にあります。

同梱runnerでwarmup除外のsteady-state CPUを再現できます。

uv run python .\examples\benchmark_sidecar_cpu.py `
  --index .\work\data\mozc-3f235b4eb6fc.sqlite3 `
  --model-cache-dir .\work\cache\huggingface\hub `
  --iterations 50 --warm-requests 5 `
  --output .\outputs\sidecar_v03_cpu.json

このWindows 11/AMD CPUでの固定8候補実測は、増分 p50/p95 14.99/17.28 ms （65.29 requests/s）、左右文脈 22.36/24.80 ms（44.55 requests/s）でした。model warmup 832.19 msは除外し、100件後の同process healthも確認しています。これは固定入力の LOCAL_PASS latencyで、端末一般・TSF・production latencyではありません。

Mozc OSS辞書から有限候補を作る

既存IMEから候補とpriorを直接受け取れる場合は、後述の通常 rerank 契約を使うのが 本来の接続です。候補境界の再現・試験用には、固定した google/mozc checkout の OSS辞書からローカル SQLite indexを作れます。

git clone https://github.com/google/mozc .\work\data\mozc
git -C .\work\data\mozc checkout 3f235b4eb6fcff7d14ef5f0fb8ee56de7ee4c732
uv run deberta-ime mozc-index `
  --dictionary-dir .\work\data\mozc\src\data\dictionary_oss `
  --output .\work\data\mozc.sqlite3 `
  --source-revision 3f235b4eb6fcff7d14ef5f0fb8ee56de7ee4c732

実測では1,289,076行を1,085,365個の (reading, surface) へ最小costで重複排除し、 48,119,808 bytesのindexを11.3秒で構築しました。manifestは入力10ファイルの個別 SHA-256、size、revision、行数をDB内へ保存します。辞書と派生indexは複数ライセンス・ 約100MBのためwheel/Hugging Faceへ同梱しません。

候補生成込みのJSONL sidecar:

uv run deberta-ime mozc-rerank `
  --index .\work\data\mozc.sqlite3 `
  --profile incremental `
  --input .\examples\mozc_requests.jsonl `
  --output .\work\mozc_response.jsonl `
  --cache-dir .\work\cache\huggingface\hub `
  --offline

incremental は左文脈だけを受け、右文脈が混入すると拒否します。bidirectional は 確定済みの左右文脈がある再変換向けです。profile設定と選択元GSD revisionは応答にも 含まれます。これは辞書単語cost順の軽量helperで、Mozc converterそのものではありません。

JSON Lines 契約

入力1行が変換対象1件です。

{
  "reading": "はし",
  "left_context": ["川", "に", "架かる"],
  "right_context": ["を", "渡る"],
  "candidates": [
    {"surface": "箸", "prior_score": 0.0},
    {"surface": "橋", "prior_score": 0.0}
  ]
}

left_context と right_context は文字列ではなく単語列です。モデルの事前学習は Juman++ 2.0.0-rc3 の分かち書きを使っているため、既存 IME が持つ文節・単語境界を 渡してください。未分割文を1要素として渡すことはできますが、評価条件と同等では ありません。

出力には、元順位、モデルスコア、混合スコア、変更有無、判断理由が含まれます。 changed=false の場合、候補順は一切変更しません。

prior_score は「大きいほど既存 IME が好む」尺度です。Mozc辞書helperでは -(cost - best_cost) / 1000 とし、GSD dev全量だけで incremental=(6.0, 2.0)、 bidirectional=(3.0, 1.5) の (prior_weight, min_margin) を選びました。既存IMEの cost尺度が異なる場合、この値を流用せず独立dev setで再調整してください。全候補0.0の DeBERTa単体はPUDで増分62.27%、双方向82.41%とMozc辞書cost順88.27%より低く、 v0.2のprofileはDeBERTaを主順位にしません。

詳細な接続規約は docs/ime-integration.md を参照してください。

Python API

from pathlib import Path

from deberta_ime import Candidate, Reranker, RerankRequest
from deberta_ime.deberta import DebertaCandidateScorer

scorer = DebertaCandidateScorer(cache_dir=Path("work/cache/huggingface/hub"))
reranker = Reranker(scorer)
result = reranker.rerank(
    RerankRequest(
        reading="はし",
        left_context=("川", "に", "架かる"),
        right_context=("を", "渡る"),
        candidates=(Candidate("箸"), Candidate("橋")),
    )
)
print(result.ranked[0].surface, result.reason)

再現評価

$env:HF_HOME = "$PWD\work\cache\huggingface"
uv run deberta-ime-benchmark-v2 dev `
  --index .\work\data\mozc.sqlite3 `
  --context-mode left_only `
  --data-dir .\work\data `
  --output-dir .\outputs `
  --stem benchmark_v02_dev_incremental `
  --model-cache-dir .\work\cache\huggingface\hub `
  --offline

# src/deberta_ime/profiles.py へdev選択値を凍結した後だけ実行
uv run deberta-ime-benchmark-v2 external `
  --index .\work\data\mozc.sqlite3 `
  --profile incremental `
  --data-dir .\work\data `
  --output-dir .\outputs `
  --stem benchmark_v02_pud_incremental `
  --model-cache-dir .\work\cache\huggingface\hub `
  --offline

uv run deberta-ime-audit-ajimee `
  --index .\work\data\mozc.sqlite3 `
  --data-dir .\work\data\ajimee-raw `
  --output-dir .\outputs

uv run deberta-ime-evaluate `
  --items .\work\evaluation\items.json `
  --predictions .\work\evaluation\predictions.json `
  --format generic `
  --dataset-name private-real-typo-heldout `
  --dataset-revision 2026-08-11-v1 `
  --dataset-license not-redistributed `
  --candidate-limit 8 `
  --output-dir .\outputs

v0.2評価器は次を固定・記録します。

• model revision 0427645e8cf44ee83b4a0b5f4498274d89e02adb
• Mozc revision 3f235b4eb6fcff7d14ef5f0fb8ee56de7ee4c732 と辞書ファイルhash
• UD Japanese-GSD revision 7bc20119f476b552635e0640644e577b6fd3606b
• UD Japanese-PUD revision a5e01a6909825bb286ec3d21c594ed442d3f76d7 とraw SHA-256
• GSD devだけで探索・凍結したprofileと、PUDで再調整していない事実
• candidate recall、oracle-in-pool条件付き精度、candidate miss込み精度
• Mozc辞書cost順、DeBERTa単体、混合rerankerの別々のAccuracy
• paired bootstrap 95%区間、McNemar exact p、改善/悪化件数
• unknown_token を除外せず既存順位維持として数えたscoring error
• CPU の load time、throughput、p50/p95 latency

候補recallは88.28%（17,352/19,655）。unknown_token 2,982件（17.18%）は 両profileとも除外せずMozc順位維持です。増分のp50/p95は21.82/52.27ms、双方向は 35.83/98.27msでした。旧v0.1の合成頻度候補評価は outputs/benchmark_full.md に履歴として残しますが、表層読みと 外部候補境界を使うv0.2の主張には使いません。

AJIMEE 200件は入力長・候補生成境界だけを監査しました。入力は最大117文字で現在の reading上限128以内ですが、文全体をMozc単語indexで引いて複数候補を得たのは1件だけです。 sequence candidate generatorがないためaccuracyは null とし、偽の比較値を作っていません。

v0.11の有限候補評価CLIでは、空または欠落した予測を入力保持の 棄却として扱い、Acc@1、候補Recall@k、入力前後のMinCER、棄却率、改善/悪化を同じartifactで 算出します。過剰補正率は clean 行が明示され、その入力自体が許容解に含まれる場合だけ算出し、 AJIMEEをclean対照へ読み替えません。さらに正解候補の欠落と選択誤りを分離し、任意の provenance / reason / margin は入力artifactの宣言値として集計します。定義とSafari端末手順は docs/evaluation-protocol-v10.md にあります。

Mozc単語costだけで全文を分割する隔離試作は、未調整AJIMEE 180件でRecall@8 27.78%だったため 公開候補器への採用を棄却しました。正解候補欠落は大きいLFMでは直せないので、350M/1.2B-JPの 比較は開始していません。

安全境界

• DeBERTa は候補生成器ではありません。正解が候補にない場合は直せません。
• accepted 以外では元の候補順を保持します。
• 候補数、候補長、文脈長、重複、空候補、非有限 prior を入力前に検査します。
• 未知 model tokenは reason=unknown_token、非有限スコアやモデル取得/読込失敗も 既存順位へ戻します。
• v0.6主画面はこのWindows PCの IFELanguage best-oneと有限のローマ字誤字仮説を使いますが、OS入力方式としての TSF登録・候補UI・署名・インストールではありません。
• 精度表は LOCAL_BENCHMARK です。provider、公開、Human GO は別ゲートです。Hub readbackは ローカル成果物 outputs/HF_UPLOAD_RECEIPT.md に分離して記録します。

一次情報とライセンス

• モデルカード: ku-nlp/deberta-v2-tiny-japanese
• Transformers: DeBERTa-v2 documentation
• 候補辞書: Mozc
• 調整データ: UD Japanese-GSD
• 外部評価: UD Japanese-PUD
• 入力境界監査: AJIMEE-Bench

モデル/GSDは配布元でCC BY-SA 4.0、PUD/AJIMEEはCC BY-SA 3.0、Mozc OSS辞書は 複数由来・複数ライセンスです。本リポジトリは重み、コーパス、Mozc辞書、派生indexを 同梱せず固定revisionから取得します。権利者の明示指示によりHub repositoryは公開ですが、 独自コードの再利用ライセンスは未決定なのでmodel cardは license: other のままです。 公開可視性は利用・改変・再配布の許諾を意味しません。将来再利用を許可する場合は、権利者が コードライセンスを別途明示する必要があります。詳細は PUBLICATION_NOTICE.md、docs/hugging-face.md、 v0.2調査は docs/v02-research.md にあります。

開発時の確認

uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv run mypy src

v0.11公開版仕様は docs/spec-v11.md、v0.6誤字救済仕様は docs/spec-v06.md、v0.5主画面仕様は docs/spec-v05.md、v0.3仕様は docs/spec-v03.md、v0.2仕様は docs/spec-v02.md、旧v0.1仕様は docs/spec.md、方式決定は docs/adr/0001-use-target-pll-reranking.md と docs/adr/0002-mozc-prior-with-frozen-confidence-profiles.md にあります。