onet-match

onet-match

将有关工作的自由文本映射到 O*NET 职业。 输入职位名称、简历要点、职位发布、项目描述、兴趣陈述和技能列表，即可获得按排名排列的 O*NET-SOC 职业，以及每个职业的关键任务、技能、知识、RIASEC 兴趣和经过校准的置信度分数。

• 在浏览器中试用：无需安装，模型会在你的设备上运行。
• 开源（MIT），可在本地运行。进行匹配无需 API 密钥或账户。
• 对全部 923 个 O*NET 31.0 职业进行微调的双编码器 + 交叉编码器重排器。在留出的 O*NET 文本上，Top-1 准确率为 51%；在较为杂乱的真人风格文本上为 65%，而 TF-IDF 基线分别为 21% 和 17%。
• 提供 Python API、CLI、REST API（FastAPI）、供 AI 助手使用的 MCP 服务，以及 Docker。笔记本电脑上每次查询约需 47 毫秒。
• 还包含其所基于的 O*NET 数据管道：批量数据库下载、Web Services 客户端和分析工具。

输入	最佳匹配（置信度）
ran the robotics club's CAD team	机器人工程师，17-2199.08（0.52）
Excel, QuickBooks, payroll, AP/AR	工资与工时记录文员，43-3051.00（0.49）
I love drawing and figuring out how machines work	机械绘图员，17-3013.00（0.41）
Looking for someone to keep our trucks on the road, diesel exp a plus	重型及牵引挂车卡车司机，53-3032.00（0.30）；第 2 名：公交车和卡车维修技师（0.21）
Sr. Backend Eng II	Web 开发人员，15-1254.00（0.43）；第 2 名：软件开发人员（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（BenjaminChan12/onet-match）下载预训练模型包（约 0.5 GB）并将其缓存。

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 会运行一个模型上下文协议 服务，提供两个只读工具：match_occupations(text, top_k) 和 get_occupation(soc)。将其添加到任意 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 重要性和等级）。每项结果还包含一个 profile，按置信度加权汇总各项匹配中的技能、知识和全部六种 RIASEC 兴趣。

使用场景

• 职业探索（EdTech）。 将学生描述自己做过或感兴趣的事情映射到 职业和技能。
• 简历和个人资料解析。 将经历要点和技能列表编码为 SOC 代码。
• 职位发布规范化。 将非正式职位名称和描述转换为标准职业。
• 劳动力与劳动力市场分析。 对大型文本集合进行批量编码。
• 职业咨询工具。 展示建议背后的任务和技能。
• LLM Agent。 基于 O*NET 为职业问题提供依据，而非自由生成（参见 llms.txt）。

详情和集成模式：docs/APPLICATIONS.md。

准确率

所有模型都在相同的留出数据集上评估。每个数值都对应 outputs/runs/ 中保存的一次运行。

model	O*NET test top-1	O*NET test top-5	messy-text test top-1	messy-text test top-5	p50 latency
TF-IDF baseline	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, off the shelf	36.1%	64.3%	45.4%	77.6%	6.9 ms
fine-tuned bge-base	50.2%	78.2%	65.2%	92.6%	6.8 ms
fine-tuned bge-base + reranker (served)	51.1%	79.1%	65.4%	92.9%	46.7 ms

• O*NET 测试集： 6,792 个留出的职位名称、任务陈述、工作活动和描述。
• 杂乱文本测试集： 4,703 条非正式文本片段，由不同于训练文本生成模型的另一个 LLM 编写。
• 置信度： 经温度校准，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. 根据验证数据选定权重，将两个分数混合。
4. 经过温度缩放的 softmax 将混合分数转换为校准后的置信度。

模型检索所用的职业文档中已移除验证和测试任务，因此测试文本不会泄漏到检索中。合成训练文本和测试文本由不同的 LLM 生成。详情见 docs/SYNTHETIC_DATA.md。

浏览器内演示

演示 Space 使用 transformers.js 在客户端运行相同的流程：两个模型都导出为 ONNX 并量化为 int8（约 130 MB，首次访问后会缓存）。demo/build.py 从一个 bundle 构建演示。量化和浏览器运行时会使结果略有偏差：在 800 条测试查询中，浏览器有 95% 的时间会选出与 Python 包相同的最佳匹配，top-1 准确率为 61.5%，而 Python 包为 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 在笔记本电脑 GPU（Apple Silicon，MPS）上完成一个 epoch 耗时 58 分钟。每次已保存运行所用的确切脚本都在 scripts/matching/ 中。
• 测试： pytest 完全离线运行，使用本地小型模型和模拟的 LLM。

设置 ONET_MATCH_BUNDLE=/path/to/bundle 可使用自己的模型提供服务，或设置 ONET_MATCH_HF_REPO=owner/repo 从 Hub 加载模型。

背景

本项目最初于 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 数据库信息，并依据 CC BY 4.0 许可证使用。O*NET® 是 USDOL/ETA 的商标。USDOL/ETA 未批准、认可或测试本产品。