urchade/GLiNER · 上手攻略

仓库：urchade/GLiNER
链接：https://github.com/urchade/GLiNER
分类：ai / llm-infra · 信息抽取（NER · 关系抽取 · PII 检测）
作者：spark
更新：2026-11-01

一、这是什么

GLiNER 是一个通用且轻量的命名实体识别（NER）框架。传统 NER 模型只能识别训练时预设好的固定实体类型（比如 PER/LOC/ORG），换个业务就要重新标注数据重新训练；GLiNER 换了个思路：把「实体类型」当作运行时输入的标签字符串列表，模型用双向 Transformer 编码文本，零样本（zero-shot）识别任意类型。

它不只是一个模型，而是一整套「框架 + 权重 + 生态」：

框架：pip install gliner，提供 GLiNER 类，覆盖预训练加载、推理、微调、量化、服务化全流程。
权重：HuggingFace 上的 gliner-community 组织，当前主力系列是 v2.5（gliner_small-v2.5 / medium / large / xxl），另有 knowledgator 组织下的 bi-encoder、RelEx、Decoder、StreamingSpan 等专用架构模型。
论文：原始论文 GLiNER: Generalist Model for Named Entity Recognition using Bidirectional Transformer，NAACL 2024 Long Papers（pages 5364–5376）。
生态：GLiNER2（多任务）、GLiClass（零样本分类）、GLinker（实体链接）、GLiNER.cpp（推理）、gline-rs（Rust）、gliner-spacy（spaCy）、vllm-factory（vLLM 集成）等。

维护方是 Urchade Zaratiana（原作者，现 Fastino）与 Ihor Stepanov（Knowledgator 联合创始人）。项目受 F.initiatives 与 Laboratoire Informatique de Paris Nord 资助，代码 Apache-2.0。

二、解决什么问题

核心痛点是：信息抽取里，标签体系总是比标注数据先变。法务合同要抽「违约责任条款类型」，医疗要抽「药品适应症」，风控要抽「案件要素」，每个都要单独训模型。

GLiNER 的取舍是：不做通用大模型那种「什么都用提示词解决」，而是做一个比 LLM 小两个数量级、能 CPU 跑、且标签随便换的专用抽取器。README 的原话是它的表现「competitive with LLMs several times its size, like ChatGPT and UniNER」。

它的四个具体优势：

零样本换标签：改一下 labels 列表就换任务，不用重新训练。
能跑在任何硬件上：CPU 可用，支持 INT8 量化、torch.compile、ONNX 导出。
标签可扩展到百万量级：bi-encoder 架构把文本和标签分开编码，标签嵌入可预计算，因此能扩到 100+ 乃至百万级实体类型而不掉性能。
NER 之外还能干别的：关系抽取（RelEx，单次前向同时出实体和关系，直接建知识图谱）、流式增量 NER（StreamingSpan）、多任务 token 分类。

三、快速安装

# 最简：推理
pip install gliner

# 推荐：升级到最新版（社区模型更新频繁）
pip install gliner -U

# 用 uv 更快
uv pip install gliner

# 带 Ray Serve 服务化支持
uv pip install gliner[serve]     # 或：pip install gliner "ray[serve]"

环境要求未在 README 中显式声明，但依赖 PyTorch + transformers，实际需要 Python 3.9+ 与可用的 PyTorch 后端（CPU/CUDA 均可）。

开发安装：

git clone https://github.com/urchade/GLiNER.git
cd GLiNER
pip install -e ".[dev]"
ruff check . --fix && ruff format .   # 提交前必须过 Ruff

官方文档站：https://urchade.github.io/GLiNER （当前文档版本 0.2.24，2026-10-31 查证）。

四、核心用法

4.1 零样本实体抽取（最常用）

from gliner import GLiNER

model = GLiNER.from_pretrained("gliner-community/gliner_small-v2.5")

text = """
Cristiano Ronaldo dos Santos Aveiro (born 5 February 1985) is a Portuguese
professional footballer who plays as a forward for and captains both Saudi Pro
League club Al Nassr and the Portugal national team.
"""

labels = ["person", "date", "organization", "location"]
entities = model.predict_entities(text, labels, threshold=0.5)

for entity in entities:
    print(entity["text"], "=>", entity["label"])

README 给出的输出：

Cristiano Ronaldo dos Santos Aveiro => person
5 February 1985 => date
Al Nassr => organization
Portugal => location

threshold 控制置信度门槛，直接决定召回与精度的取舍——标签多、结果太吵就调高，漏了就调低。

4.2 加速与量化

model = GLiNER.from_pretrained(
    "gliner-community/gliner_small-v2.5",
    map_location="cuda",
    quantize=True,            # FP16
    compile_torch_model=True,  # torch.compile
)

README 给出的量化收益（注意均为「up to」，厂商口径，需自行 benchmark）：

手段	收益	质量影响
`torch.compile`	最高约 1.5× 加速	无质量损失
FP16（`quantize=True`）	显存减半	几乎无损失
FP16 + compile	最高约 1.9× GPU 推理加速	几乎无损失
INT8	显存再减 2×	需要 QAT 训练的模型才能保住精度

4.3 服务化（高吞吐 / 多用户）

python -m gliner.serve --model gliner-community/gliner_small-v2.5 --dtype fp16

from gliner.serve import GLiNERClient

client = GLiNERClient()   # 默认连 http://localhost:8000/gliner
results = client.predict(
    ["John works at Google", "Paris is in France"],
    labels=["person", "organization", "location"],
)

服务端提供动态批处理、显存感知的批大小自适应（防 CUDA OOM）、常见批大小预编译 kernel、Ray 多副本水平扩展，以及语言无关的 HTTP API。

4.4 微调（少样本）

数据集准备成 JSON，然后：

python train.py --config configs/config.yaml

或直接编程调用：

model.train_model(
    train_dataset=train_data,
    eval_dataset=eval_data,
    output_dir="models",
    max_steps=10000,
    per_device_train_batch_size=8,
    learning_rate=1e-5,
    bf16=True,
)

另有 Colab 微调笔记本、合成数据生成 notebook（examples/synthetic_data_generation.ipynb）。

4.5 五种架构怎么选

架构	说明	示例模型
Uni-encoder	原始架构，零样本强，约 50 种实体类型以内	`urchade/gliner_multi_pii-v1`
Bi-encoder	文本与标签分开编码，可扩到海量标签	`knowledgator/gliner-bi-base-v2.0`
RelEx	实体 + 关系联合抽取，一次前向建图	`knowledgator/gliner-relex-large-v1.0`
GLiNER Decoder	混合架构，实体类型由小 decoder 生成，最灵活	`knowledgator/gliner-decoder-large-v1.0`
StreamingSpan	因果 span 模型，增量 NER + 滚动预测	`knowledgator/gliner-stream-pii-v1.0`

五、典型适用场景

合规与 PII 脱敏：覆盖 40+ 类个人数据（SSN、信用卡号、护照、邮箱、IBAN 等），支持 100+ 语言，文档流水线批量打码。
知识图谱构建：RelEx 一次抽取实体与关系，喂给 Graph RAG / 语义检索。
大规模实体抽取：bi-encoder 对数百万文档打上成百上千种标签，标签嵌入预计算是性能关键。
垂直领域 NER：医疗、法律、金融语料上少量标注即可微调。
检索增强：把用户 query 解析成结构化实体，提升搜索与 RAG 召回。

六、坑与注意（7 条）

Uni-encoder 标签数有上限（约 50 种）。现象：标签一多就明显掉召回。影响：业务里实体类型上百时 uni-encoder 不够用。修复：换 bi-encoder 架构（knowledgator/gliner-bi-base-v2.0）。
INT8 量化会掉精度，除非模型经过 QAT 训练。现象：INT8 部署后 F1 明显下滑。影响：线上质量回归。修复：只用 QAT 训练过的 checkpoint 做 INT8，或退回 FP16。
threshold 是最容易被忽视的调参项。现象：零样本抽出一堆噪声实体或漏掉关键实体。影响：下游知识图谱被污染。修复：拿一批标注样本扫 threshold，0.5 只是起点不是最优值。
训练与推理用的标签集合必须一致。现象：微调后线上零样本调用泛化很差。影响：微调白做。修复：微调数据里的标签名与推理 labels 列表严格对齐（同名、同拼写）。
README 的加速倍数是「up to」口径。现象：实测达不到 1.9×。影响：容量规划偏差。修复：先在自己硬件上 benchmark 再定容量；torch.compile 还有首次编译延迟，冷启动场景要算进去。
模型与库版本一起漂。现象：升级 gliner 后老 checkpoint 加载报错或精度变化。影响：线上事故。修复：锁版本（pip install gliner==x.y.z），模型卡上记录加载时的库版本。
第三方依赖许可需自查。现象：商业分发时合规不过。影响：法务风险。修复：仓库 Apache-2.0，但 gliner-community 组织下各模型卡许可可能不同（如早期 v0/v1 是 cc-by-nc-4.0，v2 起为 apache-2.0），分发前逐个核对模型卡 License 字段。

七、与同类对比

方案	标签灵活性	资源消耗	关系抽取	典型选择理由
GLiNER	零样本，换标签不重训	极低，CPU 可跑	支持（RelEx）	边缘部署、成本敏感、标签体系多变
传统 NER（spaCy / BERT-CRF）	低，标签固定	低	需另接	标签稳定、要求确定性最高
LLM 提示词抽取（GPT/Claude 等）	最高	极高，慢且贵	靠提示词	零样本边界极模糊、需推理式理解
GLiNER2 / GLiNER.cpp / gline-rs	同 GLiNER	低	视模型	需要多任务统一或 C++/Rust 高性能推理

一句话：标签稳定、数据多、用 spaCy 就够；标签多变、要跑在 CPU 或边缘设备、要同时抽关系，选 GLiNER；只有当抽取逻辑需要真正的推理理解、且不在乎成本与延迟时，才值得上 LLM。

八、一句话推荐结论

推荐。 它把「标签随业务变」这个 NER 领域最烦人的问题用零样本优雅解掉了，同时保持了小模型该有的轻量和 CPU 可部署性——在合规脱敏、Graph RAG 实体抽取这类「标签杂、要量大、要便宜」的场景里，它几乎是当下最务实的选择；唯一要盯紧的是架构选型（标签超过 50 种换 bi-encoder）和 INT8 必须配 QAT 模型。

附：本文引用与核验记录

一手来源（2026-10-31 / 2026-11-01 抓取） - https://github.com/urchade/GLiNER（HTML 渲染页） - https://raw.githubusercontent.com/urchade/GLiNER/main/README.md（原文） - https://urchade.github.io/GLiNER（文档站，版本 0.2.24，经 web_search 摘要确认） - https://huggingface.co/gliner-community（模型清单，经 web_search 摘要确认） - 仓库卡：organized/repo_cards/4783-urchade-gliner.md

⚠️ 不确定 / 待核处 1. 加速倍数（1.5× / 1.9× / 2× 显存）全部为 README 的「up to」厂商口径，未见对应 benchmark 表格与硬件条件，未自行实测。 2. 具体 pip 包版本号未查到：README 与文档站均未在抓取内容中给出 gliner 的确切发布版本；文档站标注 0.2.24，但这是文档版本，不等同于 pip 包版本。文中因此只写 pip install gliner -U，未写死版本号。 3. Uni-encoder「约 50 种实体类型」上限为 README 原文表述，未找到具体评测依据。 4. bi-encoder「百万标签」能力的依据是论文标题《The Million-Label NER》(arXiv:2602.18487) 与 README 表述，未核对论文中的实验规模与指标。 5. 未核对 GLiNER.cpp / gline-rs / vllm-factory 等生态项目的成熟度与维护状态，仅按 README 表格转述。 6. 未执行任何代码（按任务边界：只读公开内容，不 clone、不跑代码），所有 API 签名均照抄 README 示例，未经运行验证。