onet-match

onet-match

仕事に関する自由記述を O*NET 職業に対応付けます。 職種名、履歴書の箇条書き、求人情報、プロジェクトの説明、興味の表明、スキルリストを入力すると、主要なタスク、スキル、知識、RIASEC 興味、調整済み信頼度スコアを含む、順位付けされた O*NET-SOC 職業が出力されます。

• ブラウザーで試す：インストール不要で、モデルはお使いのデバイス上で動作します。
• オープンソース（MIT）で、ローカルで動作します。対応付けに API キーやアカウントは必要ありません。
• 全 923 件の O*NET 31.0 職業を対象とした、ファインチューニング済みのバイエンコーダーとクロスエンコーダーによる再ランカーを使用しています。Top-1 精度は、保留した O*NET テキストで 51%、人が書いた雑多な形式のテキストで 65% です。TF-IDF ベースラインの 21% と 17% を上回ります。
• Python API、CLI、REST API（FastAPI）、AI アシスタント向け MCP サーバー、Docker を提供します。ノート PC でのクエリあたりの処理時間は約 47 ms です。
• 基盤となる O*NET データパイプラインも含まれています。一括データベースダウンロード、Web Services クライアント、分析ツールを利用できます。

入力	上位の一致（信頼度）
ran the robotics club's CAD team	Robotics Engineers, 17-2199.08 (0.52)
Excel, QuickBooks, payroll, AP/AR	Payroll and Timekeeping Clerks, 43-3051.00 (0.49)
I love drawing and figuring out how machines work	Mechanical Drafters, 17-3013.00 (0.41)
Looking for someone to keep our trucks on the road, diesel exp a plus	Heavy and Tractor-Trailer Truck Drivers, 53-3032.00 (0.30); #2 Bus and Truck Mechanics (0.21)
Sr. Backend Eng II	Web Developers, 15-1254.00 (0.43); #2 Software Developers (0.10)。見逃しの例です。シニア度を示すタイトルは、既知の弱点です。

提供されるモデルの実際の出力は、outputs/examples/readme_examples.json に保存されています。

クイックスタート

pip install "onet-match[matching]"

from onet_match import match

result = match("ran the robotics club's CAD team", top_k=5)
for m in result.matches:
    print(m.soc, m.title, m.confidence)
print(result.profile["riasec_code"])      # aggregate interest code, e.g. "RIC"

パッケージは onet_match としてインポートし、onet-match コマンドを提供します。 初回の呼び出し時に、Hugging Face Hub から事前学習済みモデルのバンドル（約 0.5 GB）をダウンロードし、キャッシュします（BenjaminChan12/onet-match）。

onet-match match "Excel, QuickBooks, payroll, AP/AR"          # CLI (add --json for JSON)
pip install "onet-match[matching,serve]"
onet-match serve --port 8000                                   # REST API
curl -s localhost:8000/match -H 'content-type: application/json' \
     -d '{"text": "ran the robotics club'\''s CAD team", "top_k": 3}'

REST ルート：POST /match、POST /match/batch、GET /occupation/{soc}、GET /health。リクエストとレスポンスの仕様、および Docker の設定については、docs/API.md をご覧ください。

AI アシスタントからの使用（MCP）

onet-match mcp は、読み取り専用の 2 つのツール match_occupations(text, top_k) と get_occupation(soc) を備えた Model Context Protocol サーバーを起動します。任意の MCP クライアント（Claude Desktop、Cursor、VS Code など）に追加できます。

{
  "mcpServers": {
    "onet-match": {
      "command": "uvx",
      "args": ["--from", "onet-match[mcp]", "onet-match", "mcp"]
    }
  }
}

uv を使わない場合は、pip install "onet-match[mcp]" を実行し、"command": "onet-match", "args": ["mcp"] を使用します。リモートサーバーの場合は、onet-match mcp --transport streamable-http --port 8001 を実行します。

各一致結果に含まれる情報

soc、title、confidence（調整済み、0～1）、score、major_group とそのタイトル、job_zone、riasec_code、description、top_tasks、top_skills、top_knowledge（O*NET の重要度とレベルを含む）が含まれます。各結果には、信頼度で重み付けして、すべての一致結果にわたるスキル、知識、6 つすべての RIASEC 興味を集約した profile も含まれます。

ユースケース

• キャリア探索（EdTech）。 学生が行ったことや興味のあることについて話した内容を、職業やスキルに対応付けます。
• 履歴書とプロフィールの解析。 職務経験の箇条書きやスキルリストを SOC コードに対応付けます。
• 求人情報の正規化。 非公式な職種名や説明を標準的な職業に変換します。
• 労働力と労働市場の分析。 大規模なテキストコレクションを一括でコード化します。
• キャリアカウンセリングツール。 提案の根拠となるタスクやスキルを提示します。
• LLM エージェント。 自由生成ではなく O*NET に基づいて職業に関する質問に回答します（llms.txt を参照）。

詳細と連携パターンについては、docs/APPLICATIONS.md をご覧ください。

精度

すべてのモデルを同じホールドアウト分割で評価しています。すべての数値は、outputs/runs/に保存された実行結果に基づいています。

モデル	O*NET テスト top-1	O*NET テスト top-5	雑多なテキストのテスト top-1	雑多なテキストのテスト top-5	p50 レイテンシ
TF-IDF ベースライン	20.5%	40.5%	17.4%	39.2%	0.5 ms
BM25	20.7%	40.1%	24.1%	45.2%	0.2 ms
bge-base-en-v1.5、追加学習なし	36.1%	64.3%	45.4%	77.6%	6.9 ms
ファインチューニング済み bge-base	50.2%	78.2%	65.2%	92.6%	6.8 ms
ファインチューニング済み bge-base + リランカー（サービング時）	51.1%	79.1%	65.4%	92.9%	46.7 ms

• **O*NET テスト：**ホールドアウトした6,792件の職種名、タスク説明、業務活動、職務説明。
• **雑多なテキストのテスト：**学習テキストを生成したものとは別のLLMが作成した、4,703件の非形式的なスニペット。
• **信頼度：**温度スケーリングで較正、ECE 0.037。
• **全結果：**入力タイプ別の表、較正、アブレーション、学習曲線、エラー分析はdocs/RESULTS.mdにあります。

仕組み

flowchart LR
    B["O*NET 31.0 database<br/>(bulk download)"] --> C["Occupation catalog<br/>923 occupations"]
    C --> P["Labeled pairs<br/>titles · tasks · activities"]
    C --> S["LLM-written messy text<br/>train: model A · test: model B"]
    P --> T["Fine-tune bi-encoder<br/>+ cross-encoder reranker"]
    S --> T
    T --> BU["Model bundle<br/>(Hugging Face Hub)"]
    BU --> API["match() · onet-match CLI · REST API"]

1. ファインチューニング済みのバイエンコーダー（bge-base）が入力を埋め込み、最も近い20の職業を検索します。
2. ファインチューニング済みのクロスエンコーダーが、その20件を再スコアリングします。
3. 検証データで選んだ重みを使って、2つのスコアをブレンドします。
4. 温度スケーリングしたソフトマックスにより、ブレンドしたスコアを較正済みの信頼度に変換します。

検証タスクとテストタスクは、モデルが検索する職業ドキュメントから除外されているため、テストテキストが検索に漏れることはありません。合成の学習テキストとテストテキストは、異なるLLMから生成されています。詳細はdocs/SYNTHETIC_DATA.mdをご覧ください。

ブラウザー内デモ

デモ Spaceでは、transformers.jsを使い、同じパイプラインをクライアント側で実行します。両方のモデルをONNXにエクスポートし、int8に量子化しています（約130 MB。初回訪問後はキャッシュされます）。demo/build.pyはバンドルからデモをビルドします。量子化とブラウザーのランタイムにより、結果にはわずかな差が生じます。800件のテストクエリでは、ブラウザーがPythonパッケージと同じ最上位の候補を選ぶ割合は95%で、top-1精度は61.5%対62.6%です（outputs/demo/browser_parity.json）。重要な用途にはPythonパッケージをお使いください。

O*NET データパイプライン

onet_data_collectorパッケージ（onet-collect）は、認証情報なしでO*NETデータベースのリリースをダウンロードして検証します。また、キーワード検索、職業の詳細、フラット化されたプロファイルを提供するO*NET Web Servicesのラッパー機能もあります。docs/COLLECTOR.mdをご覧ください。

onet-collect bulk download                         # download + verify the latest O*NET database
onet-match collect "healthcare" "technology"       # Web Services search (free O*NET account, see .env.example)
onet-match eda | keywords | cluster                # classic analysis: coverage, keyword attribution, TF-IDF clusters

独自のモデルをトレーニングする

git clone https://github.com/Benjamin-V-Chan/onet-match && cd onet-match
pip install -e ".[dev]"
onet-match matching build-data          # O*NET catalog, labeled pairs, splits
scripts/matching/reproduce.sh           # every model, ablation and the results report
onet-match matching bundle "<spec>" --run <run>   # package a model for serving

• 合成テキスト：WITH_SYNTH=1 TRAIN_LLM=<model> EVAL_PROVIDER=<provider> EVAL_LLM=<model> scripts/matching/reproduce.shを実行すると、雑多な学習テキストとテストテキストも生成されます。それぞれ異なるLLMを使用します。LLM APIキーが必要です。docs/SYNTHETIC_DATA.mdをご覧ください。
• **トレーニング時間：**bge-baseは、ノートPCのGPU（Apple Silicon、MPS）で1エポックを58分で完了しました。保存された各実行の元となったスクリプトは、scripts/matching/にあります。
• テスト：pytestは、ローカルの小型モデルとモックLLMを使って完全にオフラインで実行できます。

独自のモデルをサービングするにはONET_MATCH_BUNDLE=/path/to/bundleを設定するか、Hubからモデルを読み込むにはONET_MATCH_HF_REPO=owner/repoを設定してください。

背景

このプロジェクトは、もともと2024年に、O*NETの職業データを大規模に分析するオープンソースの教育テクノロジーツールとして、また工学コースの卒業制作プロジェクトの一環として開発されました。その分析パイプライン（EDA、職業のクラスタリング、キーワードの帰属）は、後にProject Leoの本番製品に統合され、他社や他のプロジェクトでの関連作業にも影響を与えています。

2026年には、意味に基づく職業マッチングを中心に再構築され、以前のONET-Data-Collectorリポジトリが統合されました。

引用

@software{chan_onet_match,
  author = {Chan, Benjamin},
  title  = {onet-match: mapping free text to O*NET occupations},
  url    = {https://github.com/Benjamin-V-Chan/onet-match},
  year   = {2026}
}

ライセンスとデータの帰属

コードはMITライセンスです。詳細はLICENSEをご覧ください。

本製品には、米国労働省雇用訓練局（USDOL/ETA）のO*NET 31.0 Databaseの情報が含まれており、CC BY 4.0ライセンスに基づいて使用しています。O*NET®はUSDOL/ETAの商標です。USDOL/ETAは本製品を承認、推奨、またはテストしていません。