Skip to content
BranchesTags

Repository files navigation

jargon-engine · 行业黑话翻译引擎

把行业黑话翻译成接地气、搞笑、好懂的人话

PyPI CI Publish License Python Terms

translate lookup search

jargon-engine 是什么？

新人进一个行业，最懵的就是满屏黑话。jargon-engine 把「赋能业务、形成闭环、颗粒度对齐」翻译成人话——既给正经解释，也给带梗的搞笑版，还能整句重写。

它基于 AC 自动机 实现毫秒级匹配，内置 10,388 条去重词条，覆盖互联网 + AI 全行业 12 大分类。提供 Python SDK / REST API / CLI 三种接入方式，可独立部署，也可作为路由嵌入任意 FastAPI 项目。

from jargon_engine import Engine

engine = Engine()
result = engine.translate("这个方案要赋能业务，形成闭环")
print(result.translated)
# 这个写满套路的PDF要给你装个外挂，让你干得更溜。，绕一圈回来，接头了，没断线。

特性

能力 说明
🚀 毫秒级检索 AC 自动机一次扫描匹配全部词条，万级词库 translate 仅 4ms
🧠 万级词库 10,388 条去重词条，12 大行业，生产管线持续扩充
😂 三种风格 funny 搞笑人话版 / plain 正经版 / explain 带例句详解
🔌 三种接入 Python SDK / REST API / CLI，任选其一
🧩 可嵌入 FastAPI 路由可 include_router 进任意现有项目
🛡️ API 健壮 Pydantic 校验、CORS、API Key 鉴权、统一错误处理、404/400/422
⚡ 高性能 lookup O(1) 字典索引、search 预计算缓存
📦 数据分离 引擎运行时与词库生产管线物理隔离，互不依赖

快速开始

安装

pip install jargon-engine            # SDK + CLI
pip install "jargon-engine[api]"     # 加上 REST API（FastAPI + uvicorn）

Python SDK

from jargon_engine import Engine

engine = Engine()
result = engine.translate("要赋能业务，形成闭环，注意颗粒度")

print(result.translated)   # 翻译后的人话
print(result.hits)         # 命中词条详情
print(result.elapsed_ms)   # 耗时（毫秒）

REST API

jargon-engine serve --port 7861

curl -X POST http://localhost:7861/api/jargon/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"赋能业务形成闭环","style":"funny"}'

CLI

jargon-engine translate "赋能业务形成闭环"
jargon-engine lookup "赋能"
jargon-engine stats
jargon-engine serve --port 7861

REST API

端点总览

方法 路径 功能 状态码
GET /api/health 健康检查（免鉴权） 200
GET /api/jargon/translate/health 子路由健康 200
POST /api/jargon/translate 整段黑话 → 人话 200 / 400 / 422
GET /api/jargon/terms/{word} 单个词条详情 200 / 404
GET /api/jargon/search 模糊搜索词库 200 / 422
GET /api/jargon/stats 词库统计 200

鉴权

设置环境变量 JARGON_API_KEY 后，所有 /api/jargon/* 端点需携带请求头：

X-API-Key: <你的key>
# 或
Authorization: Bearer <你的key>

未设置该变量时不启用鉴权（开发模式）。/api/health 始终免鉴权，供负载均衡探活。

POST /api/jargon/translate

请求体：

字段 类型 必填 默认 说明
text string 是 - 待翻译文本，长度 ≥ 1
style string 否 funny funny / plain / explain
industry string 否 null 限定行业；支持别名 developer→tech
llm_polish bool 否 false 是否 LLM 润色（需注入润色器）
include_untracked bool 否 false 是否返回未收录候选词

响应（毫秒级）：

{
  "ok": true,
  "original": "这个方案要赋能业务，形成闭环",
  "translated": "这个写满套路的PDF要给你装个外挂，让你干得更溜",
  "hits": [
    {
      "word": "赋能",
      "plain": "为个人或组织提供能力或条件",
      "funny": "给你装个外挂，让你干得更溜",
      "industry": "internet",
      "example": "我们要赋能一线团队 → 给他们工具和权限，让他们自己飞",
      "aliases": ["加持", "赋能业务", "持续赋能"]
    }
  ],
  "untracked": [],
  "stats": {
    "total_terms": 10388,
    "matched": 2,
    "elapsed_ms": 4.1,
    "mode": "dictionary"
  }
}

GET /api/jargon/search

curl "http://localhost:7861/api/jargon/search?q=agent&industry=ai&limit=10"
参数 类型 默认 约束
q string "" 关键字
industry string - 合法行业
limit int 20 1-100

错误处理

所有错误统一 JSON 格式：

状态码 场景 响应
400 industry 不存在 {"detail": "未知的 industry: xyz..."}
401 API Key 无效 {"detail": "无效或缺失的 API Key"}
404 词条不存在 {"detail": "词条 xxx 不存在"}
422 参数校验失败 {"detail": [{"loc": [...], "msg": "..."}]}
500 内部错误 {"ok": false, "error": "内部服务错误"}

Python SDK

from jargon_engine import Engine

engine = Engine()                          # 内置词库
engine = Engine(extra_tsv_dir="./my")      # 合并自定义词库

result = engine.translate(
    "赋能业务，形成闭环",
    style="funny",           # funny / plain / explain
    industry=None,           # None=全部，或指定行业
    llm_polish=False,
    include_untracked=False,
)

engine.lookup("赋能")         # O(1) 查词
engine.search("agent", industry="ai", limit=10)  # 模糊搜索
engine.stats()                # {"total": int, "by_industry": dict}

注入 LLM 润色器

def my_polish(text: str, hits: list) -> str | None:
    # 调用任意 LLM 返回润色整句；返回 None 则保留词典模式结果
    ...

engine = Engine(llm_polish=my_polish)
engine.translate("...", llm_polish=True)

词库

词库以 TSV 存储在 data/seed/，每行一条，按行业分文件。加词 = 加一行，PR 合并即可，git diff 友好。

字段 说明
word 主词
industry 所属行业 id
aliases 别名（分号分隔，匹配时一并命中）
plain 正经解释
funny 搞笑人话版
example 例句对比（黑话 → 人话）
weight 匹配权重（越大越优先）
source 来源（数据归属追溯）

行业分类

单一事实来源在 src/jargon_engine/industries.py，新增行业只需在此登记。

id 名称 id 名称
internet 互联网通用 marketing 市场与增长
product 产品 operations 运营
tech 技术 design 设计与体验
ai AI 与大模型 finance 商业与投融资
data 数据 workplace 职场与管理
hr 人力资源 ecommerce 电商与零售

别名：developer → tech。

架构

┌─────────────────────────────────────────────┐
│            API 层（FastAPI）                 │
│  app.py · deps.py · cli.py                  │
│  Pydantic 校验 · CORS · API Key · 错误兜底  │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│            Engine（引擎入口）                │
│  加载词库 → 构建索引 → 翻译/查词/搜索        │
│  O(1) lookup · 预计算 search · 行业 resolve │
└──────┬──────────────────┬───────────────────┘
       │                  │
┌──────▼──────┐  ┌────────▼────────┐
│ Translator  │  │    Matcher      │
│ 词典命中→   │◄─│ AC 自动机       │
│ 语境重组→   │  │ 最长优先·fail链 │
│ LLM 润色    │  │ 行业过滤·去重叠 │
└─────────────┘  └─────────────────┘
       │                  │
┌──────▼──────────────────▼───────────────────┐
│        Store · Models · Industries          │
│  TSV 加载 · merge 合并 · Pydantic v2        │
└─────────────────────────────────────────────┘

词库生产管线（独立组件，与引擎运行时隔离）：
┌─────────────────────────────────────────────┐
│            tools/pipeline/                  │
│  expand_wordlists · llm_generate · merge    │
│  validate · import/*（外部数据源）          │
└─────────────────────────────────────────────┘

关键设计：

  • 引擎与生产管线分离：src/jargon_engine/ 是运行时（打进 wheel），tools/pipeline/ 是离线词库生产（不打包），两者无共享执行环境
  • 启动时建索引：加载词库 + AC 自动机 + dict 索引 + search 缓存，一次构建反复用
  • Engine 单例：lru_cache 避免每请求重建
  • 无状态抓取：生产管线不生成/存储完成状态指标，仅读已有输出续跑

词库生产管线

万级词库靠管线生产，位于 tools/pipeline/（与引擎运行时物理隔离）：

合并开源词表（MIT/CC BY-SA 来源）
    ↓
LLM 扩充行业词单（expand_wordlists.py）
    ↓
LLM 批量生成释义（llm_generate.py：funny/plain/example/aliases）
    ↓
合并去重（merge.py）+ 校验（validate.py）
    ↓
人工审校 + 社区共建（PR 持续加词）

python tools/pipeline/validate.py data/seed/*.tsv
python tools/pipeline/merge.py --sources a.tsv b.tsv --out merged.tsv
python tools/pipeline/expand_wordlists.py \
  --wordlist tools/pipeline/import/wordlists/ai.txt --industry ai --target 900 \
  --out tools/pipeline/import/wordlists/ai.txt
python tools/pipeline/llm_generate.py \
  --wordlist tools/pipeline/import/wordlists/ai.txt --industry ai \
  --out data/seed/ai_generated.tsv

需配置 DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL / DEEPSEEK_MODEL。外部数据来源见 THIRD_PARTY_NOTICES.md。

配置

变量 默认 说明
JARGON_API_KEY - API Key 鉴权，未设置则不启用
JARGON_CORS_ORIGINS * 允许的跨域来源，逗号分隔；生产请收紧
JARGON_EXTRA_TSV_DIR - 额外 TSV 词库目录，合并到内置词库
DEEPSEEK_API_KEY - 词库生产管线用，引擎运行不需要

部署

独立部署

pip install "jargon-engine[api]"
JARGON_API_KEY=your-secret jargon-engine serve --host 0.0.0.0 --port 7861

嵌入现有 FastAPI 项目

from fastapi import FastAPI
from jargon_engine.api.app import create_router

app = FastAPI()
app.include_router(create_router(), prefix="/api/jargon")

生产建议

  • uvicorn jargon_engine.api.app:create_app --factory --workers 4 多进程
  • Nginx 反向代理做 TLS、限流、缓存
  • 收紧 JARGON_CORS_ORIGINS 为实际前端域名
  • 启用 JARGON_API_KEY 防止 llm_polish 被滥用产生 LLM 费用

开发

pip install -e ".[dev,api]"
pytest                 # 46 用例
ruff check .           # lint
jargon-engine serve --port 7861   # 开发服务

路线图

里程碑 状态 内容
v0.1 基础引擎 ✅ 已发布 AC 自动机匹配、词典翻译、REST API、CLI、12 大行业
v1.0 工程化 ✅ 已发布 API 规范化（Pydantic/CORS/鉴权/错误处理）、O(1) 索引、测试覆盖、CI/CD、引擎与生产管线分离
v1.1 生态 🚧 进行中 PyPI 发布、Docker 部署、前端接入、更多行业（法律/教育/医疗）
v2.0 国际化 📋 规划中 英文社区支持、中英双向翻译、多语言释义
v2.x 智能化 📋 规划中 LLM 润色内置、分词改进、SQLite FTS5 倒排、词条贡献后台

近期 TODO

  • 补 translator LLM 润色分支与 CLI 的集成测试
  • 加 pre-commit hook（ruff + pytest）
  • Dockerfile 与 docker-compose 示例
  • 词库去重审计：跨文件同义词统一 aliases

贡献

  1. Fork 仓库并拉取分支
  2. 加词：在 data/seed/<行业>.tsv 追加一行，跑 python tools/pipeline/validate.py data/seed/*.tsv 校验
  3. 加行业：在 src/jargon_engine/industries.py 的 INDUSTRIES 登记
  4. 改代码：跑 pytest 与 ruff check . 确保通过
  5. 提 PR，描述变更与动机

词库贡献请确保 funny 版接地气、不生硬、不冒犯；外部数据来源请在 THIRD_PARTY_NOTICES.md 登记版权。

许可证

MIT — Copyright © 2026 renhuayixia

本项目基于 MIT 协议开源，允许任意改造、二次开发、商用，但必须在衍生项目中保留原作者版权声明与许可声明。词库数据来源及版权见 THIRD_PARTY_NOTICES.md。

About

行业黑话翻译引擎：把黑话翻译成接地气、搞笑、好懂的人话。万级词库，REST API 一键接入。

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages