(一篇踩坑记录。所有数字都是我自己跑出来的,代码开源在 cjkfold。)
先讲现象
我在做一个中文 RAG 检索。资料是自己传的 PDF,问的问题就在里面,答案也是原话。
但检索答不上来。
不是"答得不好",是根本检索不到。我把模型换大、阈值调低、切块调小、加 rerank —— 全都没用。
最后我做了件很朴素的事:把资料里的文本抽出来,直接搜。
>>> "颜色" in extracted_text
False
但那段文本在屏幕上明明写着"颜色"。
真正的问题在字符层
我把那个字单独拎出来看码位:
>>> [hex(ord(c)) for c in "颜色"]
['0x989c', '0x2f8a']
第二个字符是 0x2f8a,而正常的"色"是 0x8272。
它长得和"色"一模一样,但是另一个字。
| 你看到的 | 实际拿到的 | 它是什么 |
|---|---|---|
| 色 | U+2F8A | KANGXI RADICAL COLOR(康熙部首·色) |
| 角 | U+2EC6 | CJK RADICAL SIMPLIFIED HORN(CJK 部首补充·角) |
| 竹 | U+2EAE | CJK RADICAL BAMBOO(CJK 部首补充·竹) |
PDF 的文字层里,很多排版字体用的是"部首字符"来画这些部件。渲染出来毫无区别,抽出来就是另一个码位。
所以:
"颜色" in 文本→False- 关键词搜索 → 搜不到
- 向量检索 → 关键词那部分的相似度完全没贡献
- 去重、缓存、ground truth 比对 → 全部开始出错
而且它不报错。 这是最坏的一种 bug:静态检查发现不了,单元测试发现不了(除非你恰好用了这几个字),线上表现出来只是"搜不到"。
第一反应:NFKC。但它只能修一半
遇到 Unicode 兼容问题,标准答案是 unicodedata.normalize("NFKC", text)。
我先试了。康熙部首那一块,它完美解决——214 个字符,214 个都能还原。
然后我扫了另一块,CJK 部首补充区(U+2E80–U+2EFF),115 个字符:
| 区块 | 字符数 | NFKC 能还原 |
|---|---|---|
康熙部首 U+2F00–U+2FDF | 214 | 214(100%) |
CJK 部首补充 U+2E80–U+2EFF | 115 | 2(1.7%) |
113 个原样不动。
也就是说:如果你只做 NFKC,你以为你修好了,其实只修了半个问题。剩下那一半会安静地继续坏。
为什么 Unicode 不给这块做映射
这不是遗漏,是故意的。
NFKC 做的是"兼容分解"——把兼容变体折叠成标准形式。而 CJK 部首补充区里的那些字符,Unicode 认为它们是独立编码的部首字形,不是某个已有汉字的兼容变体。所以按规范,它们就不该有兼容映射。
设计上有道理,对做检索的人来说是个坑。
正解:用对属性
Unicode 15.1(2023)加了一个属性,专门治这个:EquivalentUnifiedIdeograph。
它直接给出"这个部首字符等价于哪个汉字",而且——这是关键——它区分了那些名字上看起来是一组的字符。
举个例子。⺂ ⺃ ⺄ 三个字符的 Unicode 名字分别是:
CJK RADICAL SECOND ONE
CJK RADICAL SECOND TWO
CJK RADICAL SECOND THREE
看着像同一个部首的三种写法,对吧?
实际上它们对应的汉字是三个不同的字:乛、乚、乙。
任何"按名字匹配"的做法在这里必然出错。 只能查官方数据。
我实测了覆盖率:
| NFKC 能修 | 加官方表之后 | |
|---|---|---|
| CJK 部首补充区 115 个字符 | 2 | 114 |
剩下那一个(U+2E80 CJK RADICAL REPEAT)本来就没有对应汉字,留着不动是对的。
我自己写的时候踩的坑
官方数据文件是纯文本,解析起来看着很简单。但里面有几个地方会让"随手写"的版本静悄悄地错:
1. 多对一的区间写法
文件里有这种行:
2E8C..2E8D ; 5C0F
意思是"这两个字符都等价于 小"。如果你按"左右等长一对一"解析,这一行会直接报错或者被跳过——丢字符。
这类行有 5 条,按常规解析会丢掉 11 个字符。
2. 超出 BMP 的转义
表里有些目标字符在 U+FFFF 以上(CJK 扩展 B/C 区)。如果你的生成代码写的是:
f'"{chr(cp)}": "\\u{target:04x}"'
当 target 是 0x25AD7 时,\u25ad7 里的 \u 只能读 4 位十六进制——Python 会把它解析成 \u25ad 再加一个字符 7。
一个字符变成两个。
后果是 fold("⺮") 不会返回 竹,而是吐出一串污染文本的垃圾。不报错,只是把你的数据弄坏。
我表里正好有 23 条这样的,全中。
3. 版本错位
官方数据跟的是最新 Unicode,而 Python 自带的 unicodedata 可能落后。Python 3.9 带的是 Unicode 13,表里有个目标字符在它眼里"还没分配"。
折叠本身不受影响(就是换个码位),但你查它的名字会拿到空。
4. 边界判断
别图省事直接对整段文本做 NFKC。NFKC 会把全角标点也改掉:
>>> unicodedata.normalize("NFKC", ",;()")
',;()'
中文标点变成英文标点。如果你的文本还要展示或存储,这是破坏性的。
正确做法是只折叠该折叠的字符,别碰其他。
顺带发现:排序也是反的
修完字符层之后,我又撞上一个相关的问题。
纯向量检索对精确 token 不敏感。我实测过一份资料:包含查询原话的那份文档,向量分 0.29;一份毫不相干但很短的文档,0.36。
排序整个是反的。
原因不难理解——短文档的话题单一,embedding 更"紧",余弦相似度天然虚高。长文档内容杂,向量被稀释。
这在有编号、代号、专有名词的场景里特别致命:PU-7788-ZX 这种字符串,embedding 基本看不见它。
修法很直接:把"查询片段在文档里逐字命中"这件事,加成到向量分上。
我实测的效果(同一组文档,同一组向量分):
只用向量分:
0.410 紫色 ← 无关的短文档
0.290 本文档定义了紫色独角兽协议的编号规则… ← 真正该排第一的
加上精确命中加分之后:
0.457 本文档定义了紫色独角兽协议的编号规则…
0.410 紫色
顺序回来了。
做成了一个小库
这一整套我打包成了 cjkfold,零依赖:
pip install cjkfold
from cjkfold import fold
fold("标准颜⾊值与⻆色按钮")
# '标准颜色值与角色按钮'
命令行可以先体检你的语料:
$ cjkfold check extracted.txt
extracted.txt: 3 look-alike character(s) (1 kangxi, 2 radical-supplement)
1:4 ⾊ U+2F8A -> 色 U+8272 (KANGXI RADICAL COLOR)
1:7 ⻆ U+2EC6 -> 角 U+89D2 (CJK RADICAL SIMPLIFIED HORN)
2:5 ⺮ U+2EAE -> 𥫗 U+25AD7 (CJK RADICAL BAMBOO)
找到就返回退出码 1,可以直接挂进入库流水线,在索引之前就把问题拦住——比事后查"为什么 retrieval 不准"容易一百倍。
检索管线接进去是三个点:
from cjkfold import fold, fold_documents, rerank
# 1. 入库前,把语料洗干净再进向量库
documents = fold_documents(loader.load())
# 2. 查询时,两边折叠方式必须一致
hits = vectorstore.similarity_search_with_score(fold(question), k=20)
# 3. 排序之前,把逐字命中补回去
documents, scores = zip(*hits)
for document, score in rerank(question, documents, scores):
...
fold_documents 和 rerank 认识 LangChain 的 Document、LlamaIndex 的 node,也认识纯字符串——但一个框架都不 import。为了 fold 一个字符串让你装整个 LangChain,这笔账不划算:框架 API 一直在变,字符串折叠不会变。
一句实话
这个库的核心其实很薄——就是查一张表。
但它解决的问题不是"怎么查表",是"你根本不知道要去查"。任何人第一反应都是 NFKC,然后以为自己修好了。
所以它真正的价值是替你省掉发现这件事的成本,以及避开上面那四个坑。
你可以现在就自查
如果你在做中文 RAG,最快的验证方法:
pip install cjkfold
cjkfold check 你的资料.pdf # 或者先把 PDF 抽成 txt
如果报了一堆 U+2Fxx / U+2Exx,那你现在的检索就是坏的——而且你大概率一直不知道。
代码:github.com/cdcailf/cjk…(MIT)