153_开源贡献：Hugging Face PR全攻略 - 从新手到核心贡献者的社区参与最佳实践指

# 配置Git全局用户信息
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 生成SSH密钥
ssh-keygen -t ed25519 -C "your.email@example.com"

# 将SSH密钥添加到ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# 创建并激活虚拟环境
python -m venv huggingface_env
source huggingface_env/bin/activate  # 在Windows上使用 huggingface_env\Scripts\activate

# 克隆Transformers仓库
git clone https://github.com/huggingface/transformers.git
cd transformers

# 安装开发依赖
pip install -e "[dev,testing]"

# 安装pre-commit钩子
pip install pre-commit
pre-commit install

# 1. 在GitHub上fork目标仓库（通过网页界面）

# 2. 克隆你fork的仓库到本地
git clone https://github.com/YOUR_USERNAME/transformers.git
cd transformers

# 3. 添加原始仓库作为上游仓库
git remote add upstream https://github.com/huggingface/transformers.git

# 4. 获取上游仓库的最新更改
git fetch upstream

# 确保你在main或master分支上
git checkout main

# 更新你的main分支以匹配上游仓库
git pull upstream main

# 创建一个新分支，使用描述性的名称
git checkout -b fix/bug-description  # 修复bug
git checkout -b feat/new-feature  # 新功能
git checkout -b docs/improvement  # 文档改进

from typing import Dict, List, Optional, Tuple, Union

def process_tokens(tokens: List[str], max_length: int = 512) -> Tuple[List[str], bool]:
    """Process tokens by truncating if exceeding max length.
    
    Args:
        tokens: List of tokens to process.
        max_length: Maximum number of tokens to keep.
    
    Returns:
        Tuple containing:
            - Processed list of tokens.
            - Boolean indicating if truncation occurred.
    """
    truncated = len(tokens) > max_length
    if truncated:
        tokens = tokens[:max_length]
    return tokens, truncated

import pytest

def test_process_tokens_no_truncation():
    tokens = ["hello", "world"]
    processed_tokens, truncated = process_tokens(tokens, max_length=5)
    assert processed_tokens == tokens
    assert not truncated

def test_process_tokens_with_truncation():
    tokens = ["hello", "world", "this", "is", "a", "test"]
    processed_tokens, truncated = process_tokens(tokens, max_length=3)
    assert processed_tokens == ["hello", "world", "this"]
    assert truncated

# 运行特定测试
python -m pytest tests/test_example.py -v

# 运行所有测试
python -m pytest

# 运行代码风格检查
black --check .
isort --check .
flake8 .

# 运行类型检查
mypy src/transformers

# 提交格式
git commit -m "Short description of changes (50 chars or less)"

# 如果需要更详细的说明，使用多行提交信息
git commit -m "Short description of changes

More detailed explanation of the changes, what problem
it solves, and why this approach was chosen.
"

# 推送你的分支到GitHub
git push origin your-branch-name

# 获取上游仓库的最新更改
git fetch upstream

# 切换到你的分支
git checkout your-branch-name

# 将上游的更改合并到你的分支
git rebase upstream/main

# 如果有冲突，解决它们并继续rebase
git add .
git rebase --continue

# 如果需要，强制推送更新后的分支
git push --force-with-lease origin your-branch-name

# 在src/transformers/metrics/classification.py中添加
import numpy as np
from typing import Dict, List, Optional, Union

def compute_matthews_correlation(y_pred: np.ndarray, y_true: np.ndarray) -> float:
    """Compute Matthews Correlation Coefficient (MCC).
    
    Args:
        y_pred: Predicted labels.
        y_true: True labels.
    
    Returns:
        Matthews Correlation Coefficient value.
    """
    # 计算混淆矩阵元素
    TP = np.sum(np.logical_and(y_pred == 1, y_true == 1))
    TN = np.sum(np.logical_and(y_pred == 0, y_true == 0))
    FP = np.sum(np.logical_and(y_pred == 1, y_true == 0))
    FN = np.sum(np.logical_and(y_pred == 0, y_true == 1))
    
    # 计算MCC
    denominator = np.sqrt((TP + FP) * (TP + FN) * (TN + FP) * (TN + FN))
    if denominator == 0:
        return 0.0
    
    mcc = (TP * TN - FP * FN) / denominator
    return mcc

def compute_metrics_classification(
    preds: np.ndarray,
    labels: np.ndarray,
    metric_name: str = "accuracy",
    average: Optional[str] = None,
) -> Dict[str, float]:
    """Compute metrics for classification tasks.
    
    Args:
        preds: Predictions from the model.
        labels: True labels.
        metric_name: Name of the metric to compute ("accuracy", "f1", "precision", "recall", "matthews_correlation").
        average: Type of averaging for multi-class classification.
    
    Returns:
        Dictionary containing the computed metric.
    """
    # 确保preds和labels形状匹配
    if preds.shape != labels.shape:
        if len(preds.shape) == 2 and preds.shape[1] > 1:
            # 将概率转换为类别
            preds = np.argmax(preds, axis=1)
    
    # 根据指定的指标计算结果
    if metric_name == "accuracy":
        return {"accuracy": np.mean(preds == labels)}
    elif metric_name == "f1":
        # 这里可以实现F1分数计算
        pass
    elif metric_name == "matthews_correlation":
        return {"matthews_correlation": compute_matthews_correlation(preds, labels)}
    else:
        raise ValueError(f"Unsupported metric: {metric_name}")

# 在src/transformers/trainer.py中更新_compute_metrics方法

def _compute_metrics(self, eval_preds):
    # 现有的代码...
    
    # 添加对matthews_correlation的支持
    if self.args.metric_for_best_model == "matthews_correlation":
        from transformers.metrics.classification import compute_metrics_classification
        return compute_metrics_classification(preds, labels, metric_name="matthews_correlation")
    
    # 现有的其他指标支持...

# tests/metrics/test_classification.py
import numpy as np
import pytest
from transformers.metrics.classification import compute_matthews_correlation, compute_metrics_classification

def test_matthews_correlation_perfect():
    # 完美预测
    y_true = np.array([1, 1, 0, 0])
    y_pred = np.array([1, 1, 0, 0])
    mcc = compute_matthews_correlation(y_pred, y_true)
    assert mcc == 1.0

def test_matthews_correlation_worst():
    # 最差预测
    y_true = np.array([1, 1, 0, 0])
    y_pred = np.array([0, 0, 1, 1])
    mcc = compute_matthews_correlation(y_pred, y_true)
    assert mcc == -1.0

def test_matthews_correlation_random():
    # 随机预测
    y_true = np.array([1, 0, 1, 0, 1, 0])
    y_pred = np.array([1, 1, 1, 0, 0, 0])
    mcc = compute_matthews_correlation(y_pred, y_true)
    # 计算预期值
    TP = 2  # 预测1且实际1的数量
    TN = 2  # 预测0且实际0的数量
    FP = 1  # 预测1且实际0的数量
    FN = 1  # 预测0且实际1的数量
    expected_mcc = (TP * TN - FP * FN) / np.sqrt((TP + FP) * (TP + FN) * (TN + FP) * (TN + FN))
    assert np.isclose(mcc, expected_mcc)

def test_matthews_correlation_edge_case():
    # 边缘情况：所有预测相同
    y_true = np.array([1, 1, 1, 0])
    y_pred = np.array([1, 1, 1, 1])
    mcc = compute_matthews_correlation(y_pred, y_true)
    assert mcc == 0.0  # 当分母为0时应返回0

def test_compute_metrics_classification_matthews():
    # 测试compute_metrics_classification函数使用MCC
    y_true = np.array([1, 1, 0, 0])
    y_pred = np.array([1, 0, 0, 1])
    result = compute_metrics_classification(y_pred, y_true, metric_name="matthews_correlation")
    assert "matthews_correlation" in result
    # 计算预期值
    TP = 1  # 预测1且实际1的数量
    TN = 1  # 预测0且实际0的数量
    FP = 1  # 预测1且实际0的数量
    FN = 1  # 预测0且实际1的数量
    expected_mcc = (TP * TN - FP * FN) / np.sqrt((TP + FP) * (TP + FN) * (TN + FP) * (TN + FN))
    assert np.isclose(result["matthews_correlation"], expected_mcc)

# docs/source/main_classes/trainer.md

## 评估指标

Trainer支持多种评估指标，包括：

- accuracy：准确率
- f1：F1分数
- precision：精确率
- recall：召回率
- **matthews_correlation**：Matthews相关系数，适用于不平衡数据集的分类评估

可以通过设置`metric_for_best_model`参数来选择用于模型选择的指标。

# examples/pytorch/text-classification/run_classification_with_mcc.py
from transformers import AutoModelForSequenceClassification, AutoTokenizer, Trainer, TrainingArguments
from datasets import load_dataset
import numpy as np

# 加载数据集
dataset = load_dataset("glue", "mrpc")

# 加载模型和分词器
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModelForSequenceClassification.from_pretrained("bert-base-uncased", num_labels=2)

# 预处理函数
def preprocess_function(examples):
    return tokenizer(examples["sentence1"], examples["sentence2"], truncation=True)

# 应用预处理
tokenized_dataset = dataset.map(preprocess_function, batched=True)

# 定义评估函数
def compute_metrics(eval_pred):
    logits, labels = eval_pred
    predictions = np.argmax(logits, axis=-1)
    from transformers.metrics.classification import compute_matthews_correlation
    return {"matthews_correlation": compute_matthews_correlation(predictions, labels)}

# 设置训练参数
training_args = TrainingArguments(
    output_dir="./results",
    evaluation_strategy="epoch",
    learning_rate=2e-5,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=16,
    num_train_epochs=3,
    weight_decay=0.01,
    metric_for_best_model="matthews_correlation",  # 使用MCC作为最佳模型的评估指标
    load_best_model_at_end=True,
)

# 创建Trainer
trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=tokenized_dataset["train"],
    eval_dataset=tokenized_dataset["validation"],
    tokenizer=tokenizer,
    compute_metrics=compute_metrics,
)

# 训练和评估
trainer.train()
trainer.evaluate()