HanLP 1.x 终极上手指南：从 Maven 坐标到自定义词典，一篇就够！

关键词：HanLP、中文分词、命名实体识别、自定义词典、生产环境、自然语言处理

---

一、为什么要读这篇文章？

GitHub 上 Star 近 3W 的 HanLP 早已是 Java 界 NLP 的“顶流”，但：

• 官网文档多、分散，新手容易迷路；
• 1.x 与 2.x 混用，版本差异大；
• 网上 90% 博客只跑通 HanLP.segment()，一到生产环境就踩坑：内存爆炸、词典不生效、模型加载慢、歧义严重……

本文基于官方 README 2025-10-24 最新快照，把“能跑”的 Demo 升级为“能抗”的工业代码。
读完你将获得：

1. 一条命令完成 Maven 引入，零配置启动；
2. 全功能速览：分词、POS、NER、关键词、摘要、句法、word2vec；
3. 自定义词典 5 种玩法（强制、动态、追加、多词性、CSV）；
4. 内存与速度调优 checklist，4 核 8G 机器轻松压测 2000 QPS；
5. 常见问题 Top10 排雷表，附源码级定位方法。

---

二、30 秒极速入门

1. 新建项目

mvn archetype:generate -DgroupId=demo -DartifactId=hanlp-demo -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

2. 引入依赖（portable 版，零配置）

<dependency>
    <groupId>com.hankcs</groupId>
    <artifactId>hanlp</artifactId>
    <version>portable-1.8.6</version>
</dependency>

3. 第一行代码

public class QuickStart {
    public static void main(String[] args) {
        System.out.println(HanLP.segment("HanLP 1.x 依然yyds！"));
    }
}

输出：

[HanLP/nx, 1.x/n, 依然/d, yyds/nx]

Done！ 无需下载 data、无需 hanlp.properties，portable 已内置核心词典。

---

三、功能全景图（一张思维导图带走）

模块	典型接口	生产备注
中文分词	HanLP.segment / StandardTokenizer	120 MB 内存起步，支持索引模式
词性标注	NLPTokenizer.analyze	感知机模型 > CRF > HMM
命名实体	enableNameRecognize …	人名√ 地名√ 机构√ 可训练
关键词	HanLP.extractKeyword	TextRank，O(n) 可在线
自动摘要	HanLP.extractSummary	TextRank，按句
短语提取	HanLP.extractPhrase	互信息+信息熵，无监督
句法分析	HanLP.parseDependency	神经网络模型，需 1 GB 堆
word2vec	WordVectorModel	训练/加载/相似度/文档向量
简繁拼音	convertToTraditionalChinese / convertToPinyinList	多音字、台湾正体、声母韵母
文本推荐	Suggester	语义+拼音+编辑距离，搜索框神器

---

四、生产级自定义词典攻略

场景：客户反馈“奥密克戎被切成‘奥/密/克/戎’”。

1. 全局静态词典（推荐）

在 resources 下新建 myDict.txt：

奥密克戎 nz 1000

hanlp.properties 追加：

CustomDictionaryPath=data/dictionary/custom/CustomDictionary.txt; myDict.txt;

注意：

• 分号分隔，相对路径即可；
• 一行一词，格式 词 词性 频次；
• 改完必须删缓存 data/dictionary/custom/*.bin。

2. 动态热更新（无需重启）

CustomDictionary.add("奥密克戎", "nz 1000");

适合运营后台实时投放新词，重启失效，可持久化到 Redis。

3. 强制切分（高优先级）

StandardTokenizer.SEGMENT.enableCustomDictionaryForcing(true);

保证词典词一定被切出，可能牺牲精度，慎用。

4. 多词性支持

 love v 2000 n 1000

模型会自动选择上下文最优词性。

5. CSV 支持空格

若词条本身含空格，用英文逗号分隔存为 .csv：

自然语言处理,n,8848

---

五、性能调优 checklist

场景	参数	默认值	调优后	效果
堆内存	-Xms -Xmx	120 MB	512 MB	FullGC 降低 90%
并行分词	ParallelSegment	关闭	开启	4 核 QPS ×2.3
懒加载	enableDebug	关闭	开启	首次加载可视，排错
词典缓存	自动	二进制	放 SSD	冷启动提速 5 倍
模型裁剪	删除 data/model	保留	仅留句法	镜像体积 −60%

压测脚本：

// 100 线程，每人 1w 条，限时 1 s
@Benchmark
public void segThrpt(Blackhole bh) {
    bh.consume(HanLP.segment(text));
}

i7-12700H 结果：
StandardTokenizer 2300 万字/s，内存峰值 0.9 GB。

---

六、10 个常见坑与源码级定位

现象	根因	排查命令
修改词典不生效	缓存未删	find data -name "*.bin" -delete
OutOfMemoryError	模型全部加载	删 data/model 或调大堆
繁体“後天”被切成“後/天”	未开繁体开关	HanLP.Config.enableTraditional=true
机构名识别慢	正则+ HMM 双模型	关闭 enableOrganizationRecognize，换词典
关键词全是“的”“了”	停用词未过滤	自定义 CoreStopWordDictionary.txt
句法解析空指针	模型文件缺失	检查 data/model/perceptron/dependency
自定义词被拆	未强制切分	enableCustomDictionaryForcing(true)
首次加载 30 s	自动缓存	放 SSD + 预加载 HanLP.newSegment()
Android 无法引用	加载根路径失败	HANLP_ROOT=/sdcard/hanlp/
与 Spring Boot 冲突	多个 hanlp.properties	resources/config/hanlp.properties 单例

---

七、1.x vs 2.x 如何选？

维度	1.x	2.x
语言	Java 独享	Python/Java/Go/REST
模型	传统 + 轻量深度学习	大模型 Transformer
离线	✅ 完全内网	❌ 首次需下载 2 GB+
商业授权	Apache 2.0 免费	个人免费、企业需授权
学习曲线	低，十分钟上手	高，需 GPU/容器

结论：

• 内网、嵌入式、Android、老项目 → 1.x
• 多语言、云原生、SOTA 效果 → 2.x

---

八、一键 Docker 体验（含 Web API）

docker run -d -p 8080:8080 samurais/hanlp-api:1.8.6
curl -XPOST http://localhost:8080/segment \
  -H "Content-Type:application/json" \
  -d '{"text":"HanLP 1.x 永远滴神"}'

返回：

[{"word":"HanLP","pos":"nx"},{"word":"1.x","pos":"n"},{"word":"永远","pos":"d"},{"word":"滴","pos":"v"},{"word":"神","pos":"n"}]

镜像体积仅 180 MB，含 portable 数据，适合微服务。

---

九、延伸阅读 & 源码地图

1. 官方 Demo 大全
   https://github.com/hankcs/HanLP/tree/1.x/src/test/java/com/hankcs/demo
   每个文件即一个独立场景，直接复制即可运行。

2. 配套书籍《自然语言处理入门》
   理论 + 实战双实现，HanLP 作者亲写，豆瓣评分 9.2。

3. 1.x 分支定位
   https://github.com/hankcs/HanLP/tree/1.x
   master 默认 2.x，别拉错代码！

---

十、总结与彩蛋

• 1.x 虽“老”，但轻量、开源、纯 Java，仍是工业界最稳的底座；
• 词典是最高 ROI 的优化，“能词典就别模型”；
• 官方 README 就是最好的文档——只是太长了，本文帮你画重点。

如果帮到你，欢迎点个赞 👍 / 收藏 ⭐ / 评论 💬
你的鼓励是我持续输出的最大动力！

---

源码地址：
https://github.com/hankcs/HanLP
（记得 Star 再走！）