企业官网建设流程全解析

• 教程
• 人工智能
• 大模型
• NLP
• 微调

导读

本文是 smol-course 项目（v1/7_inference/inference_pipeline.md）中"基础推理"章节的完整技术指南。你将在本教程中掌握 🤗 Transformerspipeline抽象的核心原理（预处理、模型推理、后处理三阶段）、使用HuggingFaceTB/SmolLM2-1.7B-Instruct等小模型完成文本生成的基本流程、各类生成参数与设备配置的实战用法，以及如何通过 FastAPI 把推理能力封装成 HTTP 服务。读完本文后，你可以独立完成从"加载模型生成一段文本"到"搭建一个可对外提供服务的推理接口"的完整链路，并理解 pipeline 方案在生产场景下的边界与替代选择。

Pipeline 的工作原理：自动化推理的三阶段

pipeline是 🤗 Transformers 提供的高层抽象，它屏蔽了模型架构细节与前后处理逻辑，让开发者只需关心业务逻辑。它把从"原始输入"到"可读输出"的机器学习工作流压缩为三个关键阶段：

预处理阶段（Preprocessing）Pipeline 首先把原始输入转换为模型可消费的格式，这一阶段随输入模态不同而不同：

• 文本输入：经过 tokenizer 分词（tokenization），把文本转换为模型友好的 token ID 序列。在 smol-course 的依赖环境中，分词由tokenizers==0.20.3提供底层实现（见 requirements.txt）；
• 图像输入：被缩放（resize）并归一化（normalize），以满足视觉模型的要求；
• 音频输入：通过特征提取（feature extraction）生成声谱图（spectrogram）或其他表示形式。

模型推理阶段（Model Inference）在 forward pass 过程中，pipeline 负责：

• 自动对输入进行批处理（batching），提升处理效率；
• 将计算放置到最优设备上（CPU / GPU）；
• 在支持的条件下应用半精度（FP16）等性能优化。

后处理阶段（Postprocessing）最后，pipeline 把模型的原始输出转换为有用的结果：

• 将 token ID 解码回可读文本；
• 把 logits 转换为概率分数；
• 按具体任务格式化输出（例如分类标签、生成文本等）。

这种抽象让你把精力放在应用逻辑上，而把模型推理的技术复杂度交给 pipeline 处理。从 smol-course 的课程脉络看，pipeline 甚至能自动处理 chat template——units/en/unit1/2.md 指出，使用 pipeline 调用聊天模型时"你甚至不需要知道 chat template 格式"，它会根据模型在 Hub 上的 tokenizer 配置自动套用正确的模板、完成分词与生成、返回带角色信息的结构化输出，并管理生成参数与停止条件。

基本用法：用 pipeline 进行文本生成

以下是使用 pipeline 进行文本生成的最基本形式：

from transformers import pipeline # 使用特定模型创建 pipeline generator = pipeline( "text-generation", model="HuggingFaceTB/SmolLM2-1.7B-Instruct", torch_dtype="auto", device_map="auto" ) # 生成文本 response = generator( "Write a short poem about coding:", max_new_tokens=100, do_sample=True, temperature=0.7 ) print(response[0]['generated_text'])

要点说明：

• model="HuggingFaceTB/SmolLM2-1.7B-Instruct"指向 smol-course 课程围绕的 SmolLM2 系列指令微调模型。该系列包含不同规模（如 135M、1.7B），其中-Instruct后缀表示经过指令微调、能遵循指令并展开对话的变体，而基础版（如HuggingFaceTB/SmolLM2-135M）只做下一个 token 的预测——这一区分在 v1/1_instruction_tuning/chat_templates.md 中有详细说明；
• torch_dtype="auto"让库根据设备能力自动选择合适的浮点精度（如 GPU 上自动使用半精度）；
• device_map="auto"由accelerate库驱动（smol-course 环境中accelerate==1.1.1，见 requirements.txt），自动把模型各层分配到可用设备上；
• 输出结构response[0]['generated_text']是 pipeline 的标准返回格式——response是一个列表，每个元素对应一次生成结果，其中generated_text为生成文本（对聊天模型而言，该字段是包含完整对话的列表，需取最后一个元素作为助手回复，见 units/en/unit1/2.md 中的用法）。

关键配置选项详解

模型加载：从 CPU 到自动设备分配

pipeline 支持多种设备放置策略，你可以按运行环境选择：

# CPU 推理 generator = pipeline("text-generation", model="HuggingFaceTB/SmolLM2-1.7B-Instruct", device="cpu") # GPU 推理（0 号 GPU） generator = pipeline("text-generation", model="HuggingFaceTB/SmolLM2-1.7B-Instruct", device=0) # 自动设备放置 generator = pipeline( "text-generation", model="HuggingFaceTB/SmolLM2-1.7B-Instruct", device_map="auto", torch_dtype="auto" )

三种方式的适用场景：

需要注意，device_map="auto"依赖accelerate库提供设备映射能力，这是 smol-course 环境默认安装的依赖（accelerate==1.1.1，见 requirements.txt），如果环境未安装该依赖，则需回退到显式指定device的方式。

生成参数：控制输出质量与多样性

生成参数决定模型如何从概率分布中选择下一个 token，它们是控制输出质量的关键：

response = generator( "Translate this to French:", max_new_tokens=100, # 生成文本的最大长度 do_sample=True, # 使用采样而非贪心解码 temperature=0.7, # 控制随机性（越高越随机） top_k=50, # 限制候选为概率最高的 k 个 token top_p=0.95, # 核采样（nucleus sampling）阈值 num_return_sequences=1 # 生成的不同结果数量 )

各参数的作用与建议：

• max_new_tokens：限制本次生成新增的 token 数量上限，防止无限生成长文本；
• do_sample：False（默认）时使用贪心解码，始终选取概率最高的 token，输出稳定但缺乏多样性；True时开启采样，允许模型随机选择 token；
• temperature：对 logits 做温度缩放后再取 softmax，温度越低输出越确定，越高越发散；典型取值区间在 0.5～1.0，本文示例使用 0.7；
• top_k：只保留概率最高的前 k 个 token 参与采样，避免低概率 token 干扰；
• top_p：核采样阈值，累计概率达到该值的 token 集合才参与采样，与top_k可组合使用；
• num_return_sequences：一次输入生成多少个不同结果，适合需要候选答案的场景。

在 smol-course 的其他单元中，这些参数同样通过generation_config字典以批量方式传给 pipeline，例如 units/en/unit1/2.md 中展示了把max_new_tokens、temperature、do_sample、top_p、repetition_penalty等参数打包成字典后用于多轮对话生成的方式，这说明生成参数既可逐个传参，也可集中配置。

处理多输入：利用批处理提升效率

Pipeline 可以借助批处理（batching）高效地同时处理多个输入：

# 准备多个 prompt prompts = [ "Write a haiku about programming:", "Explain what an API is:", "Write a short story about a robot:" ] # 高效处理所有 prompt responses = generator( prompts, batch_size=4, # 每次一起处理的 prompt 数量 max_new_tokens=100, do_sample=True, temperature=0.7 ) # 打印结果 for prompt, response in zip(prompts, responses): print(f"Prompt: {prompt}") print(f"Response: {response[0]['generated_text']}\n")

batch_size=4表示模型一次前向传播同时处理 4 条输入，能显著减少逐条推理带来的调度开销。当输入数量超过batch_size时，pipeline 会自动分批完成全部输入的处理。需要注意的是，pipeline 层面的批处理是静态批处理——它把已收集的输入打包送入模型，这一点与后面提到的生产级连续批处理（continuous batching）不同。

在 smol-course 中，pipeline 推理也被广泛用于验证训练成果：例如 v1/3_parameter_efficient_finetuning/notebooks/finetune_sft_peft.ipynb 在 LoRA 微调合并模型后，正是通过pipeline("text-generation", model=merged_model, tokenizer=tokenizer, device=device)快速验证微调效果。这印证了 pipeline 作为"训练-推理闭环"中轻量验证手段的定位。

Web Server 集成：用 FastAPI 封装推理服务

将 pipeline 集成到 FastAPI 应用中，即可快速把推理能力暴露为 HTTP 接口：

from fastapi import FastAPI, HTTPException from transformers import pipeline import uvicorn app = FastAPI() # 全局初始化 pipeline（进程内只加载一次模型） generator = pipeline( "text-generation", model="HuggingFaceTB/SmolLM2-1.7B-Instruct", device_map="auto" ) @app.post("/generate") async def generate_text(prompt: str): try: if not prompt: raise HTTPException(status_code=400, detail="No prompt provided") response = generator( prompt, max_new_tokens=100, do_sample=True, temperature=0.7 ) return {"generated_text": response[0]['generated_text']} except Exception as e: raise HTTPException(status_code=500, detail=str(e)) if __name__ == "__main__": uvicorn.run(app, host="0.0.0.0", port=5000)

工程要点：

• 模型全局初始化：pipeline在模块加载时创建一次，避免每次请求都重新加载模型——模型加载涉及权重下载与反序列化，是非常昂贵的操作；
• 错误处理：对空输入返回 400，对内部异常返回 500，并携带具体错误信息，便于客户端诊断；
• 同步调用在 async 端点中的注意事项：模型推理是 CPU/GPU 密集型的阻塞操作，本例为教学演示直接放在 async 端点内；在高并发场景下建议改用后台线程池或独立推理进程，避免阻塞事件循环；
• 启动方式：uvicorn.run(app, host="0.0.0.0", port=5000)监听所有网卡接口的 5000 端口，便于容器化部署或远程访问。

局限性与生产环境的选择

Pipeline 非常适合原型验证（prototyping）和小规模部署，但它存在一些固有局限：

• 优化选项有限：与专用 serving 方案相比，可调的推理优化手段较少；
• 缺少高级特性：没有内置的动态批处理（dynamic batching）、连续批处理（continuous batching）等生产级能力；
• 吞吐瓶颈：对高吞吐的生产负载可能力不从心，不适合大规模在线服务。

对于高吞吐要求的生成环境，smol-course 建议转向Text Generation Inference（TGI）等专用 serving 方案。在 v1/7_inference/text_generation_inference.md 中，TGI 提供了三类 pipeline 不具备的关键能力：

• 张量并行（Tensor Parallelism）：将模型切分到多张 GPU 上，支撑更大模型的 serving；
• 连续批处理（Continuous Batching）：动态处理请求、最大化 GPU 利用率，并结合 Flash Attention、Paged Attention 等优化显著降低显存占用并提升速度；
• Token 流式输出（Token Streaming）：基于 Server-Sent Events 实时逐 token 返回响应，降低首 token 延迟，适用于聊天类实时应用。

因此，一个合理的工程决策路径是：开发与原型阶段用 pipeline 快速验证，生产部署阶段切换到 TGI 或其他专用 serving 方案。这种"由简到繁"的两阶段选型思路正是 v1/7_inference/README.md 中模块概述的核心主张。

深入阅读

• v1/7_inference/README.md：推理模块总览，包含 pipeline 推理与 TGI 生产部署的完整学习路径；
• v1/7_inference/text_generation_inference.md：TGI 生产级部署指南，覆盖 REST API、huggingface_hub客户端、OpenAI 兼容接口与模型准备（safetensors 转换、4-bit 量化）；
• units/en/unit1/2.md：pipeline 与 chat template 的自动化处理机制，以及多轮对话与generation_config的高级用法；
• v1/1_instruction_tuning/chat_templates.md：SmolLM2 基础模型与指令微调变体的区别、ChatML 模板结构；
• requirements.txt：smol-course 完整依赖环境（transformers==4.46.3、torch==2.5.1、accelerate==1.1.1、tokenizers==0.20.3等），本文所有代码在该版本组合下运行。

• 教程
• 人工智能
• 大模型
• NLP
• 微调