简介本资源是一套面向AI算法工程师、大模型研究者及高校科研人员的大语言模型效果评测工具代码聚焦主观题与客观题双维度性能评估解决模型输出质量量化难、评测流程不统一等实际问题。压缩包共142个文件含102个CSV用于记录多轮测试指标如准确率、F1值、响应一致性等21个JSON承载模型配置与评测参数6个核心Python脚本实现CLI与Web双模式演示辅以图片、文档及依赖说明文件整体26.62MB结构清晰、开箱即用。已有348人学习下载可直接复用评测框架开展模型对比实验提供完整配置管理机制、标准化数据记录格式及可视化资源支持便于快速构建私有评测流水线显著降低大模型效果验证门槛。1. 为什么你跑通了 LLM 推理却不敢说“评测结果可信”——基于 Python 的大语言模型效果评测代码设计不是写个 prompt 就完事你本地加载了 Qwen2-7B用 transformers 跑通了 generate()输入“请写一首关于春天的五言绝句”它真给你输出了押韵的四句你又试了 Llama3-8B加了 few-shot 示例回答逻辑也像模像样。但当你要向团队汇报“模型 A 在中文问答上比 B 高 3.2 个百分点”时卡住了评测脚本是手敲的 5 行 for 循环测试集是同事微信发来的 12 条截图评分靠人工打分表 Excel 手填——这不是评测这是玄学抽签。基于 Python 实现的大语言模型效果评测代码设计源码核心不在“能跑”而在“可复现、可拆解、可归因”。它要解决的是同一份 prompt 换个 temperature0.3 和 0.7 结果差一倍你该信哪个模型在“法律条款解释”上准确率 92%但在“合同漏洞识别”上跌到 41%这个断层怎么定位评测结果受 tokenizer 差异、后处理规则、答案标准化方式影响有多大本文不讲论文里的抽象指标BLEU/ROUGE 已死只讲一线工程师每天真实面对的——如何用纯 Python 构建一套最小可行、开箱即用、改三行就能测新模型的效果评测流水线。适合刚跑通 LLM 推理、正被业务方追问“到底准不准”的算法工程师、MLOps 工程师和想把 demo 升级为产品级能力的技术负责人。2. 评测框架不是工具链堆砌而是三层契约数据契约、执行契约、评估契约大语言模型效果评测的混乱根源在于三类契约缺失数据没约定格式和边界比如“是否允许模型输出额外解释文字”执行没约定调用方式和容错比如超时怎么处理、空响应怎么归类评估没约定打分逻辑和归一化规则比如“答对核心要点但多写了无关内容”算几分。Python 实现的评测代码设计本质是用代码显式固化这三层契约。我一般会先搭一个EvalPipeline类骨架它不依赖任何特定模型 API只定义接口契约# eval_pipeline.py from abc import ABC, abstractmethod from typing import List, Dict, Any, Optional class EvalDataset(ABC): 数据契约定义评测数据必须满足的结构 abstractmethod def __len__(self) - int: ... abstractmethod def __getitem__(self, idx: int) - Dict[str, Any]: ... property abstractmethod def required_fields(self) - List[str]: ... class ModelRunner(ABC): 执行契约定义模型调用必须遵守的协议 abstractmethod def run(self, prompt: str, **kwargs) - str: ... abstractmethod def batch_run(self, prompts: List[str], **kwargs) - List[str]: ... class Evaluator(ABC): 评估契约定义打分逻辑必须实现的接口 abstractmethod def score(self, pred: str, ref: Any, **kwargs) - float: ... abstractmethod def aggregate(self, scores: List[float]) - Dict[str, float]: ...提示这三个抽象基类不是为了炫技而是为了强制解耦。当你换用 vLLM 替代 transformers 时只需重写ModelRunner子类当业务方要求新增“事实一致性”维度时只需新增一个Evaluator子类老代码完全不动。契约即文档契约即测试入口。2.1 数据契约落地用 Pydantic 定义强类型评测样本拒绝“字典键名拼错导致全量评测静默失败”评测数据常以 JSONL 文件存储但字段名大小写、嵌套层级、缺失值处理极易出错。用dict.get(answer, )看似安全实则掩盖了数据质量问题。我们用 Pydantic V2 定义EvalSample模型让校验发生在数据加载第一刻# data_models.py from pydantic import BaseModel, Field, validator from typing import Optional, List, Union class EvalSample(BaseModel): id: str Field(..., description唯一标识用于追踪错误样本) prompt: str Field(..., min_length1, description模型输入提示词) reference: Union[str, List[str], Dict] Field( ..., description标准答案支持单答案/多答案/结构化答案 ) category: str Field(defaultgeneral, description题目类别用于分组统计) metadata: Optional[Dict[str, Any]] Field(default_factorydict) validator(prompt) def prompt_not_empty(cls, v): if not v.strip(): raise ValueError(prompt cannot be empty or whitespace only) return v.strip() class Config: extra forbid # 禁止多余字段防止JSON里混入 typo 字段加载时直接用EvalSample.parse_obj(line)一旦 JSONL 中某行prompt为空或含非法字段立刻抛ValidationError并打印具体行号。这比运行 2 小时后发现 30% 样本reference是null强一万倍。常见做法是把评测集按category分成子集如math,code,reasoning每个子集对应一个独立的EvalDataset实现便于后续按能力维度切片分析。2.2 执行契约落地封装模型调用为可插拔 Runner兼容 HuggingFace / vLLM / Ollama / 自研 API不同部署方式调用差异极大transformers 需要model.generate()tokenizer.decode()vLLM 要走AsyncLLMEngineOllama 是 HTTP POST自研服务可能是 gRPC。统一抽象为ModelRunner后各实现专注自身逻辑# runners/hf_runner.py from transformers import AutoTokenizer, AutoModelForCausalLM import torch class HFModelRunner(ModelRunner): def __init__( self, model_name: str, device: str cuda, max_new_tokens: int 512, temperature: float 0.0, # 默认 greedy decoding top_p: float 1.0, repetition_penalty: float 1.0 ): self.tokenizer AutoTokenizer.from_pretrained(model_name) self.model AutoModelForCausalLM.from_pretrained( model_name, torch_dtypetorch.float16, device_mapauto ) self.device device self.max_new_tokens max_new_tokens self.temperature temperature self.top_p top_p self.repetition_penalty repetition_penalty def run(self, prompt: str, **kwargs) - str: inputs self.tokenizer(prompt, return_tensorspt).to(self.device) outputs self.model.generate( **inputs, max_new_tokensself.max_new_tokens, temperatureself.temperature, top_pself.top_p, repetition_penaltyself.repetition_penalty, do_sampleself.temperature 0, pad_token_idself.tokenizer.eos_token_id ) return self.tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokensTrue)关键参数说明temperature0.0强制 greedy search保证结果确定性评测阶段必须关闭随机性pad_token_idself.tokenizer.eos_token_id避免生成中因 padding token 导致截断do_sampleself.temperature 0自动切换采样/贪婪模式省去手动 if 判断。注意batch_run方法在 HF 下需用generate的 batch 版本但要注意显存爆炸风险。实际项目中我通常用torch.no_grad()model(input_ids)logits.argmax(-1)手动 decode比generate快 3 倍且可控性强。2.3 评估契约落地从字符串匹配到语义打分Evaluator 的三级演进路径评测不能只看 exact matchEM——模型答“北京是中国首都” vs “中华人民共和国首都为北京”EM0 但语义正确。Evaluator 设计需分三级Level 1规则引擎Regex / Keyword / Substring适用于答案格式严格场景如选择题、日期提取class RegexEvaluator(Evaluator): def __init__(self, pattern: str): self.pattern re.compile(pattern) def score(self, pred: str, ref: str, **kwargs) - float: return 1.0 if self.pattern.search(pred) else 0.0Level 2嵌入相似度Sentence-BERT / BGE用预训练语义模型计算cosine_similarity(embed(pred), embed(ref))from sentence_transformers import SentenceTransformer class SBERTEvaluator(Evaluator): def __init__(self, model_name: str BAAI/bge-small-zh-v1.5): self.model SentenceTransformer(model_name, trust_remote_codeTrue) def score(self, pred: str, ref: str, **kwargs) - float: emb_pred self.model.encode([pred], normalize_embeddingsTrue)[0] emb_ref self.model.encode([ref], normalize_embeddingsTrue)[0] return float(np.dot(emb_pred, emb_ref))Level 3LLM-as-a-JudgeSelf-Consistency / Multi-Perspective用更强模型对pred和ref做结构化打分如 0-5 分再取平均class LLMAssistedEvaluator(Evaluator): def __init__(self, judge_model_runner: ModelRunner): self.judge_runner judge_model_runner def score(self, pred: str, ref: str, **kwargs) - float: # 构造 judge prompt要求输出 JSON {score: 3, reason: ...} prompt f你是一个专业评测员。请对以下模型回答与标准答案的匹配度打分0-5分 [模型回答] {pred} [标准答案] {ref} 请严格按JSON格式输出{{score: int, reason: string}} try: resp self.judge_runner.run(prompt) result json.loads(resp) return max(0.0, min(5.0, float(result[score]))) / 5.0 except Exception as e: return 0.0 # 降级为 0 分不中断流程提示LLM-as-a-Judge 不是银弹。我实测发现用 Qwen2-7B 当 judge 时在数学题上打分偏严平均低 0.8 分但在开放问答上偏松。务必用小样本人工校准 judge 模型的 bias。3. 评测不是“跑一次就交差”而是构建可审计、可回滚、可对比的评测流水线评测结果要经得起质疑业务方问“上周结果是 72.3%这周变成 68.1%是模型退化还是评测变了”你得拿出证据。这就要求评测过程本身可审计——每一步输入、参数、输出都留痕。我设计的EvalPipeline核心方法如下# pipeline.py import json import time from pathlib import Path from datetime import datetime class EvalPipeline: def __init__( self, dataset: EvalDataset, runner: ModelRunner, evaluator: Evaluator, output_dir: str ./eval_results ): self.dataset dataset self.runner runner self.evaluator evaluator self.output_dir Path(output_dir) self.output_dir.mkdir(exist_okTrue) def run(self, run_id: Optional[str] None) - Dict[str, Any]: run_id run_id or frun_{int(time.time())} log_dir self.output_dir / run_id log_dir.mkdir(exist_okTrue) # Step 1: 记录本次评测元信息 meta { run_id: run_id, timestamp: datetime.now().isoformat(), dataset_info: { name: type(self.dataset).__name__, size: len(self.dataset), fields: self.dataset.required_fields }, model_info: { runner_type: type(self.runner).__name__, params: {k: v for k, v in self.runner.__dict__.items() if k not in [model, tokenizer]} # 过滤大对象 }, evaluator_info: { type: type(self.evaluator).__name__ } } with open(log_dir / meta.json, w, encodingutf-8) as f: json.dump(meta, f, ensure_asciiFalse, indent2) # Step 2: 执行评测逐样本记录原始数据 results [] for i in range(len(self.dataset)): sample self.dataset[i] try: pred self.runner.run(sample[prompt]) score self.evaluator.score(pred, sample[reference]) results.append({ id: sample[id], prompt: sample[prompt], reference: sample[reference], prediction: pred, score: score, category: sample.get(category, unknown), timestamp: datetime.now().isoformat() }) except Exception as e: results.append({ id: sample[id], error: str(e), timestamp: datetime.now().isoformat() }) # Step 3: 保存原始结果 聚合报告 raw_path log_dir / raw_results.jsonl with open(raw_path, w, encodingutf-8) as f: for r in results: f.write(json.dumps(r, ensure_asciiFalse) \n) report self.evaluator.aggregate([r[score] for r in results if score in r]) report[total_samples] len(results) report[failed_samples] len([r for r in results if error in r]) report[run_id] run_id with open(log_dir / report.json, w, encodingutf-8) as f: json.dump(report, f, ensure_asciiFalse, indent2) return report关键设计点run_id作为评测实例唯一标识支持按时间/版本回溯meta.json记录所有可变参数temperature、max_new_tokens、evaluator 类型杜绝“参数变了但没人知道”raw_results.jsonl每行一条样本结果支持用jq或 pandas 直接分析“哪些 category 失败率高”、“top-k 错误样本长什么样”report.json是给业务方看的摘要但它的数字必须能从raw_results.jsonl重新计算出来。注意raw_results.jsonl是审计黄金标准。我曾用它发现一个线上 bug模型在处理含\n\n的 prompt 时tokenizer 会意外截断导致 12% 的样本预测为空。这个 bug 在聚合报告里只是“整体准确率下降 1.2%”但查原始日志立刻定位。4. 避坑评测翻车的 4 个血泪现场以及为什么它们比模型本身更致命评测代码看似简单但实际落地时90% 的“结果不准”源于评测框架自身的缺陷而非模型能力。以下是我在 3 个大模型项目中踩过的、代价最高的坑4.1 现象同一份评测集两次运行结果相差 ±5.3%排查发现temperature0.7未固定原因评测默认开启采样而 LLM 生成具有随机性。即使设置seed不同框架HF/vLLM/Ollama的随机数种子实现不一致且seed可能被模型内部其他操作覆盖。解决强制temperature0.0do_sampleFalse并移除所有torch.manual_seed()相关代码。评测阶段不需要多样性需要确定性。若必须测采样效果应明确声明sampling_modeTrue并在报告中标注“此结果为 5 次采样平均值”。4.2 现象中文评测中exact_match准确率虚高人工抽查发现模型总在答案末尾加“。”或“”而 reference 没有原因未做答案标准化normalization。不同模型 tokenizer 对标点符号处理不同如 Qwen 加空格Llama 不加且用户输入 reference 时习惯不一致。解决在Evaluator.score()前统一清洗def normalize_text(text: str) - str: text re.sub(r[^\w\u4e00-\u9fff], , text) # 替换所有非字母、数字、中文字符为空格 text re.sub(r\s, , text).strip() # 合并多余空格 return text.lower() # 统一小写对中文影响小但保持习惯然后score(normalize_text(pred), normalize_text(ref))。注意此清洗不可用于需要保留标点的场景如代码生成需按 task 类型开关。4.3 现象vLLM 部署的模型评测速度比 HF 快 5 倍但batch_run时部分样本返回空字符串原因vLLM 的generate接口对prompt长度敏感当 batch 中某条 prompt 超过 context window整个 batch 报错并返回空。HF 会单条 fallbackvLLM 默认 batch 失败。解决在vLLMRunner.batch_run()中添加长度预检def batch_run(self, prompts: List[str], **kwargs) - List[str]: # 预检查每条 prompt 长度超长则截断或报错 max_len self.tokenizer.model_max_length - 128 # 预留生成空间 truncated_prompts [] for p in prompts: tokens self.tokenizer.encode(p, truncationTrue, max_lengthmax_len) truncated_prompts.append(self.tokenizer.decode(tokens, skip_special_tokensTrue)) # 再调用 vLLM batch generate...4.4 现象用 BGE 模型做语义相似度评测结果与人工评分相关性仅 0.42原因BGE 是通用领域模型在金融/医疗/法律等垂直领域表现骤降。且encode()默认normalize_embeddingsTrue但不同句子长度导致 embedding norm 差异影响 cosine 相似度。解决垂直领域必须微调 BGE 或换领域适配模型如bge-reranker-base改用util.cos_sim()替代手动np.dot它内部做了更鲁棒的归一化对长文本用split_sentencesmax_pooling提升稳定性from sentence_transformers.util import cos_sim def robust_encode(text: str, model) - np.ndarray: sentences sent_tokenize(text) # 按句分割 if len(sentences) 10: sentences sentences[:10] # 截断防 OOM embeddings model.encode(sentences, normalize_embeddingsTrue) return np.max(embeddings, axis0) # 句子级 max pooling提示所有这些坑都在raw_results.jsonl里留下痕迹。我的习惯是每次新评测前先用head -n 10 raw_results.jsonl | jq .prediction快速扫一眼前 10 条预测肉眼确认格式、长度、有无异常空值——这 30 秒能省去 3 小时 debug。5. 进阶技巧用“评测即测试”重构你的模型迭代闭环让每次 PR 都带评测报告评测代码的价值不该停留在“月度汇报 PPT 里的一张图”。真正的工程化是把它变成 CI/CD 流水线的一等公民——每次模型更新、prompt 优化、后处理规则调整都自动触发评测并拦截退化变更。我落地的最小可行方案如下5.1 将评测脚本转为 pytest 兼容的测试用例把EvalPipeline.run()封装成 pytest fixture让评测变成可断言的单元测试# test_eval.py import pytest from eval_pipeline import EvalPipeline from runners.hf_runner import HFModelRunner from evaluators.sbert_evaluator import SBERTEvaluator from datasets.custom_dataset import CustomEvalDataset pytest.fixture def pipeline(): dataset CustomEvalDataset(./data/qa_test.jsonl) runner HFModelRunner(Qwen/Qwen2-7B-Instruct, temperature0.0) evaluator SBERTEvaluator(BAAI/bge-small-zh-v1.5) return EvalPipeline(dataset, runner, evaluator) def test_qwen2_7b_chinese_qa(pipeline): report pipeline.run() # 关键指标断言核心能力不能退化 assert report[accuracy] 0.85, fAccuracy dropped to {report[accuracy]} assert report[failed_samples] 0, fFound {report[failed_samples]} failed samples # 保存本次通过的 report 作为 baseline with open(./baselines/qwen2_7b_qa.json, w) as f: json.dump(report, f)运行pytest test_eval.py -v --tbshort失败时直接显示哪项指标不达标。CI 中配置# .github/workflows/eval.yml name: Model Evaluation on: pull_request: paths: - models/** - prompts/** - eval/** jobs: eval: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.10 - name: Install dependencies run: | pip install -r requirements.txt - name: Run evaluation tests run: pytest test_eval.py -v5.2 构建跨模型、跨版本的横向对比报告附表格当你要选型 Qwen2 vs Llama3 vs GLM4 时手动整理 10 个维度的分数太慢。写个compare_report.py自动生成 Markdown 表格ModelQA AccuracyMath ReasoningCode GenerationAvg ScoreFailed SamplesQwen2-7B86.2%73.1%68.4%75.9%2Llama3-8B82.7%78.5%71.2%77.5%0GLM4-9B89.1%70.3%74.6%78.0%1生成逻辑很简单遍历./eval_results/run_*目录读取每个report.json提取字段用tabulate库渲染。关键在Avg Score计算——不是简单平均而是按业务权重加权# weights.yaml qa: 0.4 math: 0.3 code: 0.3 # compare_report.py with open(weights.yaml) as f: weights yaml.safe_load(f) weighted_score sum(report[k] * weights[k] for k in weights)5.3 用“错误样本聚类”替代人工抽检3 行代码定位模型盲区人工看 100 条错误样本效率极低。我用scikit-learn对prompt做 TF-IDF 向量化再用 KMeans 聚类找出高频错误模式from sklearn.feature_extraction.text import TfidfVectorizer from sklearn.cluster import KMeans import pandas as pd # 从 raw_results.jsonl 读取所有失败样本 df pd.read_json(./eval_results/run_1712345678/raw_results.jsonl, linesTrue) failures df[df[error].notna() | (df[score] 0.3)] vectorizer TfidfVectorizer(max_features1000, ngram_range(1,2)) X vectorizer.fit_transform(failures[prompt]) kmeans KMeans(n_clusters5, random_state42) failures[cluster] kmeans.fit_predict(X) # 输出每个 cluster 的 top keywords 和 sample count for cluster_id in failures[cluster].unique(): cluster_data failures[failures[cluster] cluster_id] print(f\nCluster {cluster_id} ({len(cluster_data)} samples):) # 提取该 cluster 的 top keywords tfidf_sum X[cluster_data.index].sum(axis0).A1 top_idx tfidf_sum.argsort()[-5:][::-1] print(Top keywords:, [vectorizer.get_feature_names_out()[i] for i in top_idx])实测中这个脚本帮我们发现Qwen2 在处理含“不超过”“至少”等比较级词汇的数学题时错误率高达 82%而 Llama3 在同一 cluster 仅 12%。这直接推动我们为 Qwen2 增加了比较级 prompt engineering。我坚持把评测代码当作生产环境的第一道防线——它不创造模型能力但它让每一次能力提升都可验证、可归因、可交付。现在我的团队PR 描述里必须包含eval_results/run_xxx/report.json的链接没有它合并按钮是灰色的。这听起来很重但比起上线后被客户投诉“你们模型昨天还行今天怎么不会算数了”这点重量值得扛。希望帮到你。本文还有配套的精品资源点击获取
