@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/mlops/huggingface-tokenizers/SKILL.md

@@ -0,0 +1,518 @@
+---
+name: huggingface-tokenizers
+description: 为研究和生产优化的快速 tokenizers。基于 Rust 的实现可在 <20 秒内完成 1GB 文本的 tokenization。支持 BPE、WordPiece 和 Unigram 算法。训练自定义词汇表、追踪 alignment、处理 padding/truncation。与 transformers 无缝集成。适用于你需要高性能的 tokenization 或自定义 tokenizer 训练。
+version: 1.0.0
+author: Orchestra Research
+license: MIT
+dependencies: [tokenizers, transformers, datasets]
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Tokenization, HuggingFace, BPE, WordPiece, Unigram, Fast Tokenization, Rust, Custom Tokenizer, Alignment Tracking, Production]
+
+---
+
+# HuggingFace Tokenizers - 面向 NLP 的高速 Tokenization
+
+快速、可用于生产的 tokenizers，兼具 Rust 的性能与 Python 的易用性。
+
+## 何时使用 HuggingFace Tokenizers
+
+**使用 HuggingFace Tokenizers 的场景：**
+- 需要极快的 tokenization 速度（每 GB 文本 <20 秒）
+- 从头训练自定义 tokenizers
+- 需要进行 alignment 追踪（token → 原始文本位置）
+- 构建生产级 NLP pipelines
+- 需要高效地对大型语料库进行 tokenize
+
+**性能表现**：
+- **速度**：在 CPU 上处理 1GB 文本仅需 <20 秒
+- **实现方式**：Rust 核心，配合 Python/Node.js 绑定
+- **效率**：比纯 Python 实现快 10-100 倍
+
+**建议使用替代方案的场景**：
+- **SentencePiece**：与语言无关，被 T5/ALBERT 使用
+- **tiktoken**：OpenAI 为 GPT 模型开发的 BPE tokenizer
+- **transformers AutoTokenizer**：仅用于加载预训练模型（内部使用此库）
+
+## 快速 start
+
+### 安装
+
+```bash
+# Install tokenizers
+pip install tokenizers
+
+# With transformers integration
+pip install tokenizers transformers
+```
+
+### 加载预训练 tokenizer
+
+```python
+from tokenizers import Tokenizer
+
+# Load from HuggingFace Hub
+tokenizer = Tokenizer.from_pretrained("bert-base-uncased")
+
+# Encode text
+output = tokenizer.encode("Hello, how are you?")
+print(output.tokens)  # ['hello', ',', 'how', 'are', 'you', '?']
+print(output.ids)     # [7592, 1010, 2129, 2024, 2017, 1029]
+
+# Decoding back
+text = tokenizer.decode(output.ids)
+print(text)  # "hello, how are you?"
+```
+
+### 训练自定义 BPE tokenizer
+
+```python
+from tokenizers import Tokenizer
+from tokenizers.models import BPE
+from tokenizers.trainers import BpeTrainer
+from tokenizers.pre_tokenizers import Whitespace
+
+# Initialize tokenizer with BPE model
+tokenizer = Tokenizer(BPE(unk_token="[UNK]"))
+tokenizer.pre_tokenizer = Whitespace()
+
+# Configure trainer
+trainer = BpeTrainer(
+    vocab_size=30000,
+    special_tokens=["[UNK]", "[CLS]", "[SEP]", "[PAD]", "[MASK]"],
+    min_frequency=2
+)
+
+# Train on files
+files = ["train.txt", "validation.txt"]
+tokenizer.train(files, trainer)
+
+# Save
+tokenizer.save("my-tokenizer.json")
+```
+
+**训练时间**：100MB 语料库约需 1-2 分钟，1GB 约需 10-20 分钟
+
+### 使用 padding 进行批量编码
+
+```python
+# Enable padding
+tokenizer.enable_padding(pad_id=3, pad_token="[PAD]")
+
+# Encode batch
+texts = ["Hello world", "This is a longer sentence"]
+encodings = tokenizer.encode_batch(texts)
+
+for encoding in encodings:
+    print(encoding.ids)
+# [101, 7592, 2088, 102, 3, 3, 3]
+# [101, 2023, 2003, 1037, 2936, 6251, 102]
+```
+
+## Tokenization 算法
+
+### BPE (Byte-Pair Encoding)
+
+**工作原理**:
+1. 从字符级词汇表开始
+2. 找出出现频率最高的字符对
+3. 将其合并为新的 token，并添加到词汇表中
+4. 重复此过程，直到达到设定的词汇表大小
+
+**被应用于**: GPT-2, GPT-3, RoBERTa, BART, DeBERTa
+
+```python
+from tokenizers import Tokenizer
+from tokenizers.models import BPE
+from tokenizers.trainers import BpeTrainer
+from tokenizers.pre_tokenizers import ByteLevel
+
+tokenizer = Tokenizer(BPE(unk_token="<|endoftext|>"))
+tokenizer.pre_tokenizer = ByteLevel()
+
+trainer = BpeTrainer(
+    vocab_size=50257,
+    special_tokens=["<|endoftext|>"],
+    min_frequency=2
+)
+
+tokenizer.train(files=["data.txt"], trainer=trainer)
+```
+
+**优势**:
+- 能很好地处理 OOV 词汇（将其拆分为子词）
+- 词汇表大小灵活
+- 适用于形态学丰富的语言
+
+**权衡**:
+- Tokenization 的结果依赖于合并顺序
+- 可能会出乎意料地拆分常见词汇
+
+### WordPiece
+
+**工作原理**:
+1. 从字符词汇表开始
+2. 对合并对进行评分：`frequency(pair) / (frequency(first) × frequency(second))`
+3. 合并得分最高的配对
+4. 重复此过程，直到达到设定的词汇表大小
+
+**被应用于**: BERT, DistilBERT, MobileBERT
+
+```python
+from tokenizers import Tokenizer
+from tokenizers.models import WordPiece
+from tokenizers.trainers import WordPieceTrainer
+from tokenizers.pre_tokenizers import Whitespace
+from tokenizers.normalizers import BertNormalizer
+
+tokenizer = Tokenizer(WordPiece(unk_token="[UNK]"))
+tokenizer.normalizer = BertNormalizer(lowercase=True)
+tokenizer.pre_tokenizer = Whitespace()
+
+trainer = WordPieceTrainer(
+    vocab_size=30522,
+    special_tokens=["[UNK]", "[CLS]", "[SEP]", "[PAD]", "[MASK]"],
+    continuing_subword_prefix="##"
+)
+
+tokenizer.train(files=["corpus.txt"], trainer=trainer)
+```
+
+**优势**:
+- 优先进行有意义的合并（高得分 = 语义相关）
+- 在 BERT 中被成功应用（取得了 state-of-the-art 的结果）
+
+**权衡**:
+- 如果没有匹配的子词，未知词汇将被标记为 `[UNK]`
+- 保存的是词汇表而不是合并规则（文件体积更大）
+
+### Unigram
+
+**工作原理**:
+1. 从一个庞大的词汇表（所有子串）开始
+2. 计算当前词汇表在语料库上的 loss
+3. 移除对 loss 影响最小的 tokens
+4. 重复此过程，直到达到设定的词汇表大小
+
+**被应用于**: ALBERT, T5, mBART, XLNet（通过 SentencePiece）
+
+```python
+from tokenizers import Tokenizer
+from tokenizers.models import Unigram
+from tokenizers.trainers import UnigramTrainer
+
+tokenizer = Tokenizer(Unigram())
+
+trainer = UnigramTrainer(
+    vocab_size=8000,
+    special_tokens=["<unk>", "<s>", "</s>"],
+    unk_token="<unk>"
+)
+
+tokenizer.train(files=["data.txt"], trainer=trainer)
+```
+
+**优势**:
+- 基于概率（寻找可能性最高的 tokenization 方式）
+- 适用于没有明确词语边界的语言
+- 能够处理多样化的语言上下文
+
+**权衡**:
+- 训练的计算成本较高
+- 需要调整的 hyperparameters 较多
+
+## Tokenization pipeline
+
+完整 pipeline：**Normalization → Pre-tokenization → Model → Post-processing**
+
+### Normalization
+
+清理和规范文本：
+
+```python
+from tokenizers.normalizers import NFD, StripAccents, Lowercase, Sequence
+
+tokenizer.normalizer = Sequence([
+    NFD(),           # Unicode normalization (decompose)
+    Lowercase(),     # Convert to lowercase
+    StripAccents()   # Remove accents
+])
+
+# Input: "Héllo WORLD"
+# After normalization: "hello world"
+```
+
+**常见 normalizers**:
+- `NFD`, `NFC`, `NFKD`, `NFKC` - Unicode normalization forms
+- `Lowercase()` - Convert to lowercase
+- `StripAccents()` - Remove accents (é → e)
+- `Strip()` - Remove whitespace
+- `Replace(pattern, content)` - Regex replacement
+
+### Pre-tokenization
+
+将文本拆分为类似单词的单元：
+
+```python
+from tokenizers.pre_tokenizers import Whitespace, Punctuation, Sequence, ByteLevel
+
+# Split on whitespace and punctuation
+tokenizer.pre_tokenizer = Sequence([
+    Whitespace(),
+    Punctuation()
+])
+
+# Input: "Hello, world!"
+# After pre-tokenization: ["Hello", ",", "world", "!"]
+```
+
+**常见 pre-tokenizers**:
+- `Whitespace()` - Split on spaces, tabs, newlines
+- `ByteLevel()` - GPT-2 style byte-level splitting
+- `Punctuation()` - Isolate punctuation
+- `Digits(individual_digits=True)` - Split digits individually
+- `Metaspace()` - Replace spaces with ▁ (SentencePiece style)
+
+### Post-processing
+
+为模型输入添加 special tokens：
+
+```python
+from tokenizers.processors import TemplateProcessing
+
+# BERT-style: [CLS] sentence [SEP]
+tokenizer.post_processor = TemplateProcessing(
+    single="[CLS] $A [SEP]",
+    pair="[CLS] $A [SEP] $B [SEP]",
+    special_tokens=[
+        ("[CLS]", 1),
+        ("[SEP]", 2),
+    ],
+)
+```
+
+**常见模式**：
+```python
+# GPT-2: sentence <|endoftext|>
+TemplateProcessing(
+    single="$A <|endoftext|>",
+    special_tokens=[("<|endoftext|>", 50256)]
+)
+
+# RoBERTa: <s> sentence </s>
+TemplateProcessing(
+    single="<s> $A </s>",
+    pair="<s> $A </s> </s> $B </s>",
+    special_tokens=[("<s>", 0), ("</s>", 2)]
+)
+```
+
+## Alignment 追踪
+
+追踪 token 在原始文本中的位置：
+
+```python
+output = tokenizer.encode("Hello, world!")
+
+# Get token offsets
+for token, offset in zip(output.tokens, output.offsets):
+    start, end = offset
+    print(f"{token:10} → [{start:2}, {end:2}): {text[start:end]!r}")
+
+# Output:
+# hello      → [ 0,  5): 'Hello'
+# ,          → [ 5,  6): ','
+# world      → [ 7, 12): 'world'
+# !          → [12, 13): '!'
+```
+
+**使用场景**:
+- 命名实体识别（将预测结果映射回文本）
+- 问答系统（提取答案跨度）
+- Token 分类（将标签与原始位置对齐）
+
+## 与 transformers 集成
+
+### 使用 AutoTokenizer 加载
+
+```python
+from transformers import AutoTokenizer
+
+# AutoTokenizer automatically uses fast tokenizers
+tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
+
+# Check if using fast tokenizer
+print(tokenizer.is_fast)  # True
+
+# Access underlying tokenizers.Tokenizer
+fast_tokenizer = tokenizer.backend_tokenizer
+print(type(fast_tokenizer))  # <class 'tokenizers.Tokenizer'>
+```
+
+### 将自定义 tokenizer 转换为 transformers 格式
+
+```python
+from tokenizers import Tokenizer
+from transformers import PreTrainedTokenizerFast
+
+# Train custom tokenizer
+tokenizer = Tokenizer(BPE())
+# ... train tokenizer ...
+tokenizer.save("my-tokenizer.json")
+
+# Wrap for transformers
+transformers_tokenizer = PreTrainedTokenizerFast(
+    tokenizer_file="my-tokenizer.json",
+    unk_token="[UNK]",
+    pad_token="[PAD]",
+    cls_token="[CLS]",
+    sep_token="[SEP]",
+    mask_token="[MASK]"
+)
+
+# Use like any transformers tokenizer
+outputs = transformers_tokenizer(
+    "Hello world",
+    padding=True,
+    truncation=True,
+    max_length=512,
+    return_tensors="pt"
+)
+```
+
+## 常见模式
+
+### 从迭代器训练（针对大型数据集）
+
+```python
+from datasets import load_dataset
+
+# Load dataset
+dataset = load_dataset("wikitext", "wikitext-103-raw-v1", split="train")
+
+# Create batch iterator
+def batch_iterator(batch_size=1000):
+    for i in range(0, len(dataset), batch_size):
+        yield dataset[i:i + batch_size]["text"]
+
+# Train tokenizer
+tokenizer.train_from_iterator(
+    batch_iterator(),
+    trainer=trainer,
+    length=len(dataset)  # For progress bar
+)
+```
+
+**性能表现**：处理 1GB 数据大约需要 10-20 分钟
+
+### 启用截断和 padding
+
+```python
+# Enable truncation
+tokenizer.enable_truncation(max_length=512)
+
+# Enable padding
+tokenizer.enable_padding(
+    pad_id=tokenizer.token_to_id("[PAD]"),
+    pad_token="[PAD]",
+    length=512  # Fixed length, or None for batch max
+)
+
+# Encode with both
+output = tokenizer.encode("This is a long sentence that will be truncated...")
+print(len(output.ids))  # 512
+```
+
+### 多进程处理
+
+```python
+from tokenizers import Tokenizer
+from multiprocessing import Pool
+
+# Load tokenizer
+tokenizer = Tokenizer.from_file("tokenizer.json")
+
+def encode_batch(texts):
+    return tokenizer.encode_batch(texts)
+
+# Process large corpus in parallel
+with Pool(8) as pool:
+    # Split corpus into chunks
+    chunk_size = 1000
+    chunks = [corpus[i:i+chunk_size] for i in range(0, len(corpus), chunk_size)]
+
+    # Encode in parallel
+    results = pool.map(encode_batch, chunks)
+```
+
+**加速效果**：使用 8 核可提速 5-8 倍
+
+## 性能基准测试
+
+### 训练速度
+
+| Corpus Size | BPE (30k vocab) | WordPiece (30k) | Unigram (8k) |
+|-------------|-----------------|-----------------|--------------|
+| 10 MB | 15 sec | 18 sec | 25 sec |
+| 100 MB | 1.5 min | 2 min | 4 min |
+| 1 GB | 15 min | 20 min | 40 min |
+
+**硬件环境**：16 核 CPU，基于英文维基百科数据进行测试
+
+### Tokenization 速度
+
+| Implementation | 1 GB corpus | Throughput |
+|----------------|-------------|---------------|
+| Pure Python | ~20 minutes | ~50 MB/min |
+| HF Tokenizers | ~15 seconds | ~4 GB/min |
+| **Speedup** | **80×** | **80×** |
+
+**测试条件**：英文文本，句子平均长度为 20 个单词
+
+### 内存使用
+
+| 任务 | Memory |
+|-------------------------|---------|
+| 加载 tokenizer | ~10 MB |
+| 训练 BPE (30k vocab) | ~200 MB |
+| 编码 1M 个句子 | ~500 MB |
+
+## 支持的 models
+
+可通过 `from_pretrained()` 获取预训练的 tokenizers：
+
+**BERT 家族**:
+- `bert-base-uncased`, `bert-large-cased`
+- `distilbert-base-uncased`
+- `roberta-base`, `roberta-large`
+
+**GPT 家族**:
+- `gpt2`, `gpt2-medium`, `gpt2-large`
+- `distilgpt2`
+
+**T5 家族**:
+- `t5-small`, `t5-base`, `t5-large`
+- `google/flan-t5-xxl`
+
+**其他**:
+- `facebook/bart-base`, `facebook/mbart-large-cc25`
+- `albert-base-v2`, `albert-xlarge-v2`
+- `xlm-roberta-base`, `xlm-roberta-large`
+
+浏览全部：https://huggingface.co/models?library=tokenizers
+
+## 参考资料
+
+- **[Training Guide](references/training.md)** - Train custom tokenizers, configure trainers, handle large datasets
+- **[Algorithms Deep Dive](references/algorithms.md)** - BPE, WordPiece, Unigram explained in detail
+- **[Pipeline Components](references/pipeline.md)** - Normalizers, pre-tokenizers, post-processors, decoders
+- **[Transformers Integration](references/integration.md)** - AutoTokenizer, PreTrainedTokenizerFast, special tokens
+
+## 资源
+
+- **文档**：https://huggingface.co/docs/tokenizers
+- **GitHub**：https://github.com/huggingface/tokenizers ⭐ 9,000+
+- **版本**：0.20.0+
+- **课程**：https://huggingface.co/learn/nlp-course/chapter6/1
+- **论文**：BPE (Sennrich et al., 2016), WordPiece (Schuster & Nakajima, 2012)