很多人第一次接触大模型都是从搜索引擎开始的。你搜“大模型”“Python”“预训练模型”这些词出来的内容十个里有八个都会提到 Transformers。这个名字既能指一篇论文里的神经网络架构也指 Hugging Face 开源的 Python 库还泛指整个大模型技术生态。不少新手在这里就懵了我到底要学的是哪个这篇文章就是来解决这件事的。我会从环境配置开始带你用 Python 一条龙跑通“加载预训练模型 → 中文情感分析 → 文本生成”这几个最常见的调用场景。核心库就是 transformers目标是让你看完之后能独立动手遇到报错也知道问题出在哪。适合刚入坑的开发者也适合需要快速验证业务方案的算法工程师。全文不写高深推导只讲“怎么用、为什么这么用”再加上我自己踩过的坑和排查经验。1. 先搞明白Transformers 到底指什么1.1 架构、开源库、生态三件事不能混为一谈我见过太多人在这上面绕圈子。同一个词底下其实压着三个完全不同的东西。第一个是 2017 年谷歌论文《Attention Is All You Need》里提出的 Transformer 架构。它是为了解决 NLP 里老大哥 RNN 的两个问题串行效率低、长距离依赖记不住。RNN 处理一句话必须一个字一个字往后走前面看过的信息会在后面衰减。Transformer 的注意力机制相当于在一屋子人里找人不是挨个握手过去而是直接扫一眼全场看看谁最值得关注。这段话里每个词都能直接跟其他所有词建立关联距离再远也能抓住关系。它还特别好并行GPU 一上训练效率直接起飞。第二个是 Hugging Face 机构开源的 transformers 库注意首字母是小写 t。这个库把几百种模型架构封装成了统一接口 loading 模型、切词、推理、微调几行 Python 代码就能搞定。你可以把 transformers 理解为“模型超市的收银台”不管货架上放的是 BERT、GPT、RoBERTa 还是 T5你都用同一套结账流程。第三个是大家嘴里常说的“大模型生态”。GPT、ChatGLM、Qwen、LLaMA、DeepSeek 这些名字背后全是 Transformer 架构的变体。整个领域现在的玩法也基本统一了先在海量文本上做预训练学到通用的语言能力再通过微调或者提示词把它用到具体任务上。1.2 “预训练 微调”的调用逻辑我刚入门时最困惑的一点是预训练模型到底是怎么“调用”的是不是像调用函数一样model(你好)就能出结果其实没那么玄。预训练模型训练完以后产出的是一堆权重文件存在硬盘上。你要用的就是把这堆权重加载进内存然后走一条固定的流水线用分词器tokenizer把原始文本变成模型认识的 token 编号把 token 编号变成张量喂给模型模型前向计算输出一堆数值你根据自己的任务比如分类、抽取、生成对输出做后处理。transformers 库做的就是把这个流程统一封装好。你唯一要多操心的是选哪个模型、怎么切词、输出怎么解释。这也是为什么我一直建议新人别一上来就去读模型源码先学会“调用”和“看结果”更重要。多说一句这个架构早就不是在文本里独享了。热搜里那句 “an image is worth 16x16 words”意思是把图像切成一个个小块当作“单词”序列扔进 Transformer照样能做图像识别。学会了文本侧这套调用方式之后摸多模态模型也是一样的手感。2. 环境准备Python、虚拟环境与 Transformers 依赖2.1 别用系统 Python先搞一个虚拟环境如果你以前装过很多东西直接在系统 Python 里干活早晚会碰到依赖地狱。举个特别常见的场景项目 A 需要 transformers 4.29项目 B 需要 4.45俩库版本互相踩你装一个另一个就崩。虚拟环境就是给每个项目单独开一间房间互不干扰。我建议用 Python 官方自带的venv不用额外装东西。# 创建虚拟环境名字随便起比如 llm_env python -m venv llm_env # Windows 激活 llm_env\Scripts\activate # macOS / Linux 激活 source llm_env/bin/activate激活之后命令行前面会出现(llm_env)这时候你所有 pip 操作都发生在独立环境里了。如果你用 VSCode按下CtrlShiftP输入 “Python: Select Interpreter”把解释器指到你虚拟环境目录下的 python.exe。这一步不做代码里写import transformers很可能跑起来找你系统里另一套环境。Python 版本方面别太激进也别太保守。建议用 3.9 到 3.11。3.12 现在 transformers 早就支持了但很多底层依赖比如后续你会碰到的 vLLM、CUDA 扩展包未必都跟得上。用 3.10 或者 3.11 是风险最低的选择。2.2 PyTorch 和 transformers 的安装顺序很重要很多人直接pip install transformers结果发现 import 成功一跑模型就报ModuleNotFoundError: No module named torch。因为 transformers 只是抽象层真正的计算后端是 PyTorch 或者 TensorFlow。标准操作是先装 PyTorch再装 transformers。如果你的机器只有 CPU直接pip install torch如果你有 NVIDIA 显卡想用 GPU 加速去 PyTorch 官网选择对应版本。官网会给你一段完整命令。装完后在 Python 里验证一下import torch print(torch.__version__) print(torch.cuda.is_available())如果cuda.is_available()返回 False说明 PyTorch 装成了 CPU 版常见原因是当初用了默认源安装把 GPU 版又覆盖了。重装时把 CUDA 版指定清楚就行别同时重复装两遍。接下来装核心库pip install transformers顺手再装两个以后必用的pip install datasets accelerate sentencepiecedatasets是加载和处理数据集的accelerate是多卡和混合精度训练时省事的工具sentencepiece是因为很多中文大模型和 T5 类模型的分词器依赖它。装完看着多实际上都是同一生态里的必需品。国内网络装 pip 包慢的话可以用清华源临时加速pip install transformers -i https://pypi.tuna.tsinghua.edu.cn/simple要是你已经在用国内源可以一劳永逸设置默认镜像pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple2.3 验证安装跑通第一个迷你推理环境到底行不行用最小例子说话。新建一个 Python 文件或者直接在交互环境里写from transformers import pipeline classifier pipeline(sentiment-analysis, modeluer/roberta-base-finetuned-jd-binary-chinese) print(classifier(手机质量很好做工精致))第一次运行会去 Hugging Face 下载模型文件大概几十到几百 MB要等一会儿。看到进度条走完然后输出类似[{label: positive, score: 0.99...}]的字典就说明整条链路已经通了。如果下载卡住或者一直超时先别急。大概率是网络对国外站点的访问不稳定。解决方案不是反复重试而是手动把模型文件下载下来放到本地缓存目录。最简单的办法直接用浏览器打开模型主页把config.json、pytorch_model.bin、vocab.txt等文件下载到本地某个目录然后代码里把modeluer/roberta-base-finetuned-jd-binary-chinese换成你本地目录路径。路径指向哪里transformers 就从哪里加载不需要联网。3. 第一个实战中文情感分析模型调用3.1 用 pipeline 三行代码快速出结果前面验证环境那节其实已经用了一次pipeline。它最大的价值是把整个流程压缩成了一个函数自动加载配置、自动读取标签映射、自动切词、自动做前向计算最后给你人类可读的结果。我原封不动贴一个完整的中文情感分析例子from transformers import pipeline model_path uer/roberta-base-finetuned-jd-binary-chinese classifier pipeline(sentiment-analysis, modelmodel_path) texts [ 这家酒店地理位置很好但是隔音效果太差了, 物流很快包装也很严实很满意, ] for text in texts: result classifier(text) print(text, -, result)输出会给你两个标签中的一个positive 或 negative再带一个置信度分数。不过 pipeline 对入门友好对生产不友好。为什么很多场景你需要自己控制切词长度需要把多条样本拼成一个 batch 推理需要拿到模型输出的原始数值而非最终的标签这时候直接用 pipeline 反而束手束脚。3.2 手动组装AutoTokenizer AutoModelForSequenceClassification拿同一个模型我拆给你看底层发生了什么。import torch from transformers import AutoTokenizer, AutoModelForSequenceClassification model_path uer/roberta-base-finetuned-jd-binary-chinese tokenizer AutoTokenizer.from_pretrained(model_path) model AutoModelForSequenceClassification.from_pretrained(model_path) text 手机屏幕非常清晰运行也很流畅 encoding tokenizer( text, paddingmax_length, truncationTrue, max_length128, return_tensorspt, ) with torch.no_grad(): outputs model(**encoding) logits outputs.logits probs torch.softmax(logits, dim-1) pred torch.argmax(probs, dim-1) print(probs) print(pred.item())逐个拆开说。tokenizer把文本切成模型认识的 token。中文模型的分词器通常有词表切完的 token 会对应成数字这个数字在词表里有索引模型就读这些索引进行计算。paddingmax_length是把文本统一补齐到 128 的长度。为什么要补齐因为模型内部是按矩阵批次计算的一个批次里每条样本的长度必须一样短了就得补占位符。truncationTrue是超过 128 个 token 就截断。大模型不是无限长的BERT 系列底层的位置编码一般支持到 512超过这个长度必须截断或者分片。return_tensorspt表示返回 PyTorch 张量这样可以直接丢给模型。如果写成tf就是给 TensorFlow 用的。model(**encoding)里的**encoding会把input_ids、attention_mask这类字段展开成关键字参数。attention_mask的作用是告诉模型哪些位置是真实内容、哪些是补的占位符计算注意力的时候不要把占位符当信息用。logits就是模型最原始的得分一般叫 logits不是概率。对二分类来说logits 可能是一个两个数经过 softmax 之后变成两个和为 1 的概率值哪个大类就取哪个。torch.argmax取概率最大的下标0 和 1 对应的情感类别需要看模型训练时用的标签顺序简单场景里通常 positive 和 negative 各对应一个。手动写法的最大好处是你可以把text.replace换成一批文本把它们一起 tokenizer 后 concat 成一个 batch然后一次前向推理完成。前面说的max_length也成了你能控制的参数长文本可以自己决定怎么截。如果你想部署成一个接口这些都是必须掌握的细节。3.3 中文预训练模型怎么选中文 NLP 里的模型远不止 Google 的bert-base-chinese一个。挑模型时我的习惯是看任务类型和部署资源。模型名称特点适用场景bert-base-chineseGoogle 官方中文模型中规中矩通用分类、序列标注、通用刚入门hfl/chinese-roberta-wwm-ext哈工大讯飞联合实验室出品全词掩码训练中文文本分类、语义相似度、NERhfl/roberta-wwm-ext-large参数量更大效果通常更好离线质量要求高、机器内存够hfl/rbt3参数量小、速度快线上低延迟、资源受限uer/roberta-base-finetuned-jd-binary-chinese已在下游情感分类任务上微调过中文情感正负面判断开箱即用我的经验是如果项目里有大量真实中文语料chinese-roberta-wwm-ext这类系列普遍比bert-base-chinese表现好。所谓“wwm”就是全词掩码训练时把中文的一个词整体遮挡住而不是随机遮挡单个字这让模型学到的语义更稳。但你要特别小心一件事模型和分词器必须配对使用。你可以说“我要换模型”但不要随手把 A 模型的分词器安到 B 模型上词表不一样出来的 token 完全错乱。正确姿势永远是AutoTokenizer.from_pretrained和AutoModelForSequenceClassification.from_pretrained传入同一个路径。还有个小提醒AutoModelForSequenceClassification.from_pretrained默认会用模型自己的配置文件里写好的分类数量。如果你要在一个基础 BERT 模型上自己接一个全新的分类头记得显式传num_labels5这种参数。如果你用的是别人已经微调好的分类模型就不要乱改 num_labels否则加载时会有一堆权重对不上的报错。4. 生成式大模型文本生成与调用方式4.1 自回归模型和“generate 函数的关键参数”分类模型输出的是判断生成模型输出的是新文本。现在大模型基本都属于自回归模型逐个 token 往后接每次预测下一个 token 是什么然后把新 token 拼回输入继续预测再下一个。transformers 里生成统一叫generate。我先给一个可直接跑的中文小模型例子from transformers import AutoTokenizer, AutoModelForCausalLM model_path uer/gpt2-chinese-cluecorpussmall tokenizer AutoTokenizer.from_pretrained(model_path) model AutoModelForCausalLM.from_pretrained(model_path) prompt 人工智能的未来 inputs tokenizer(prompt, return_tensorspt) outputs model.generate( **inputs, max_new_tokens64, do_sampleTrue, temperature0.8, top_p0.9, repetition_penalty1.1, ) print(tokenizer.decode(outputs[0], skip_special_tokensTrue))第一次同样会下载模型。跑完你会看到模型续写了一段话效果说不上惊艳但足够让你理解“生成”是怎么回事。参数是生成质量的关键。直接背这几个参数作用调参经验max_new_tokens 或 max_length控制生成长度新文本最多多少个 token比 max_length 直觉更好do_sample是否随机采样False 是贪心解码总是选概率最大的 token结果稳定但千篇一律temperature控制随机性越低越保守越高越放飞。0.7~0.9 是生成任务常用区间超过 1.2 容易胡言乱语top_p核采样只从累计概率前 top_p 的候选里选配合 temperature 用常用 0.9 附近top_k只从前 k 个高概率候选里选k 小一些输出稳定常见 30~50repetition_penalty重复惩罚1.1 左右能明显缓解“复读机”问题no_repeat_ngram_size禁止 n-gram 重复设置为 3即避免连续三个 token 完全重复我的调参经验是先开do_sampleTrue把temperature调到 0.8top_p调到 0.9大多数生成场景基本够用。如果发现模型一直重复一句话把repetition_penalty往上加到 1.2 或 1.3 试试如果输出太碎、毫无逻辑多半是temperature太高往下降就对了。4.2 对话模型与提示词模板生成式模型要当“对话助手”用还得处理聊天模板。现在主流模型都要求你按system、user、assistant这种角色消息格式组织输入然后再套上模型对应的模板。在较新版本 transformers 里建议直接用apply_chat_templatefrom transformers import AutoTokenizer, AutoModelForCausalLM # 这里换成你具体要用的对话模型路径比如某个中文指令微调模型 checkpoint your-chat-model-path tokenizer AutoTokenizer.from_pretrained(checkpoint) model AutoModelForCausalLM.from_pretrained(checkpoint) messages [ {role: system, content: 你是一个帮助用户解答编程问题的助手回答尽量简洁。}, {role: user, content: 在 Python 里怎么把列表去重但保持顺序}, ] inputs tokenizer.apply_chat_template( messages, return_tensorspt, add_generation_promptTrue, ) outputs model.generate(**inputs, max_new_tokens200, temperature0.7) answer tokenizer.decode(outputs[0][inputs.shape[1]:], skip_special_tokensTrue) print(answer)划重点不要自己手动拼模板。每个模型的训练模板不一样有的用|im_start|有的用[INST]拼错了对话质量滑坡。让apply_chat_template去做适配最省心这也相当于把提示词工程里的“格式层”交给库来完成。outputs[0][inputs.shape[1]:]的意思是把输入部分截掉只保留模型新生成的 token。这一步在做对话时特别常见避免把用户输入重复打印出来了。4.3 本地推理与 API 调用怎么选新手经常纠结一个问题我是自己在本地电脑部署一个大模型还是直接调用各平台提供的 API我把两种方式的取舍写清楚维度本地部署API 调用硬件要求显存和内存门槛高无门槛有网络就行部署工作量要考虑下载、量化、服务化拿 key 就能用隐私数据数据不出本地适合敏感业务数据要发出去需要合规评估响应速度可能慢小模型不太慢通常稳定有网络延迟定制微调可以自由微调模型很多平台只开放提示词级调整成本电费和硬件支出按调用量付费我给的实际建议是学习和原型验证阶段如果机器没有像样的 GPU直接用 API 最划算有一点入门级 GPU在本地跑跑 1B 到 7B 级别的量化模型体验一下部署流程真到了生产环境一般也是先把 API 作为兜底再逐步把高频路径切到本地模型。API 调用在代码层面并没有特别神秘。现在主流厂商为了兼容性普遍提供 OpenAI 兼容格式也就是你 POST 一个 JSON 到/v1/chat/completions然后接返回结果。如果要实现流式回答就是发起请求时带stream: True然后一行行读数据流。import json import requests url https://your-api-endpoint/v1/chat/completions headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json, } payload { model: your-model-name, messages: [ {role: system, content: 你是一个靠谱的中文助手。}, {role: user, content: 用一句话总结什么是大模型。}, ], stream: True, } resp requests.post(url, jsonpayload, headersheaders, streamTrue) for line in resp.iter_lines(decode_unicodeTrue): if line and line.startswith(data: ): chunk line[6:].strip() if chunk [DONE]: break # 这里拿到的是 JSON 字符串解析后取出增量文本 try: data json.loads(chunk) piece data[choices][0][delta].get(content, ) print(piece, end) except Exception: continue这段代码几乎是所有聊天机器人前端接后端的基础模板。前端的聊天窗口能一个字一个字往外蹦不是模型做得到而是后端拿着流式接口把增量内容不断推给前端前端再实时渲染。你在热搜里看到“通过 SSE 流式输出实现大模型回答实时渲染”本质就是这个循环。小白第一次写这个容易在两点上翻车。一是iter_lines拿到的是data:开头的一行需要把前缀去掉才能解析二是最后一行可能是[DONE]标记不处理的话会尝试解析成 JSON 而报错。代码里我有break直接处理。5. 常见报错与排查技巧实录5.1 高频报错速查表transformers 相关的报错信息其实翻来覆去就那么几种。我整理了一份速查表覆盖了大部分新人会遇到的情况报错现象常见原因解决办法ModuleNotFoundError: No module named torch只装了 transformers 没装 PyTorch先pip install torch再回来推理KeyError: token...或词表相关报错模型和分词器不匹配确保AutoTokenizer和AutoModel使用同一个模型路径RuntimeError: CUDA out of memory.显存不够减小 batch size 和 max_length换 fp16 或量化换更小的模型Some weights of the model checkpoint were not used加载的权重和模型结构有一部分对不上如果是微调过的模型别随便改 num_labels如果只是换了最后一个分类层这是正常提醒ImportError: cannot import name AutoModel... from transformerstransformers 版本太旧升级依赖pip install -U transformersValueError: Asking to pad but the tokenizer does not have a padding token部分 GPT2 类模型没有 pad token手动设置tokenizer.pad_token tokenizer.eos_token或者用paddinglongestOSError: Cant load model或下载中断网络不稳定Hugging Face 权重下载失败网络重试或手动下载权重到本地改成本地路径加载sentencepiece相关报错缺了分词依赖补装pip install sentencepiece这里我想展开说两个最容易让人困惑的。第一个是“Some weights ... not used”警告。这个不是报错是提醒。如果你加载一个别人微调好的分类模型但你只想要前半部分不做分类或者你改了分类数量模型加载时会发现最后的权重用不上于是给你一句提示。新手容易吓得以为是崩了其实只要最后一层对不上这属于正常。反过来的情形才是问题你想用某个模型做分类但加载后配置里的类别数是错的输出完全乱这种时候要检查num_labels。第二个是“CUDA out of memory”。显存不够是最打击新人的坑因为它是运行时才爆的。解决思路优先级是先降batch_size把一次同时推理的文本数量改小比如从 32 改到 8再降max_length长度直接影响模型内存占用还不行就换半精度用torch.dtypetorch.float16加载最后实在不行就换小模型别死磕。5.2 显存与推理速度的几条硬经验很多人问这个模型要多少显存才能跑其实有个最粗暴的估算公式模型权重显存 ≈ 参数量 × 每个参数的字节数。参数数量以 10 亿为单位也就是 1B。float32 精度下每个参数占 4 字节所以一个 1B 模型光权重就要 4 GB 内存换成 float16 就变成 2 GB再做 4bit 量化大概能压到 0.75 GB。推理时还会产生中间激活值实际上需要留更多余量。所以你在模型详情页看到“1.5B”“7B”“13B”第一反应就是把它乘上精度对应的字节数心里大概就有数了。推理提速方面有几条朴素但好使的经验。第一推理前把模型切到 eval 模式然后在预测代码外面包一层torch.no_grad()。这两步能省去生成计算图和记录梯度的开销三千字的批量推理能明显感觉到区别。第二数据聚合到 batch 里跑。不要一条一条地喂给模型比如一次推理 32 条文本虽然单条速度没变但整体吞吐提高不少。注意 batch 内的文本要补齐到同一长度所以尽量把类似长度的文本放一组避免短文本被长文本拖累。第三能用半精度就用半精度。在支持 fp16 或 bf16 的 GPU 上用低精度加载模型不仅能省一半显存很多 GPU 上推理速度还会更快。新手不用太担心精度损失绝大多数业务场景下效果差异可以接受。第四搞清楚模型的参数量。有一个临时检查方法total_params sum(p.numel() for p in model.parameters()) print(f参数量: {total_params / 1e9:.2f} B)这个数字有助于你做模型选型和硬件评估。别只看名字里是“base”还是“large”实际跑之前先算一笔账比事后爆显存强多了。5.3 排查思路先定位是环境还是代码遇到报错我先说一个特别重要的排查顺序。很多人喜欢把整段报错贴到搜索引擎然后逐条试效率极低。我的习惯是问自己三个问题第一是 import 阶段挂了还是运行阶段挂了import 挂掉九成是依赖版本问题比如 torch 没装、transformers 和 Python 版本不兼容。运行阶段挂掉再去看具体报错类型。第二是模型加载挂了还是推理挂了模型加载挂了基本是网络下载失败、权重文件缺失、模型路径不对。推理挂了多半是输入格式问题比如inputs没有attention_mask、token 长度超过模型上限、数据没有放到同一设备上。第三是显存内存不够还是代码逻辑不对显存内存不够的报错信息里通常有out of memory字眼这时候别改代码逻辑去减小 batch、换精度、换小模型。如果有shape、dim、expected这些字眼那是张量形状或者对象类型不对回到代码里检查输入格式。这套思路能帮你避开“头痛医头”的陷阱。transformers 这个库已经非常成熟了遇到问题先怀疑环境再怀疑输入数据最后才怀疑库本身这是最稳的顺序。最后分享几个我个人的习惯我自己往上踩了不少坑之后养成了一个习惯正式在业务里用某个模型之前先写一个不超过 20 行的最小验证脚本专门测试“加载权重 单条推理”是否正常。这个脚本不追求效果只追求链路通。链路通了再往上加 batch、加业务逻辑、加接口。配环境这件事最忌讳的就是在系统 Python 里堆依赖。我现在每开一个项目第一件事就是建虚拟环境。哪怕是验证一个新模型也单独开一个环境半小时装完确认不行直接删掉重来一点都不心疼。还有一个小技巧特别是对于刚开始学调用大模型的读者把下载好的模型文件统一放在本机某个目录里比如D:\models\或者~/models/然后在代码里每次都写本地路径。这样既不依赖网络也方便你在不同项目里反复复用同一份权重。手动在模型页面下载文件放到对应目录比反复折腾自动下载要省心得多。Transformers 入门真正劝退人的不是数学也不是模型原理而是环境和报错。把这两关过了你已经赢了半场。剩下的事情基本上就是照着模型文档试用、改参数、看效果然后在一次次尝试里慢慢理解模型的行为。文中的示例代码都是可以直接跑的你拿本地环境试一遍亲手跑通一次推理这篇指南才算是真正用上了。