SmallThinker-3B-Preview一键部署教程：Ubuntu20.04环境快速搭建指南

SmallThinker-3B-Preview一键部署教程Ubuntu20.04环境快速搭建指南最近在开源社区里SmallThinker-3B-Preview这个模型挺火的。它是个3B参数规模的开源大模型主打的就是一个“小而精”推理速度快资源占用相对友好特别适合个人开发者或者小团队拿来快速验证想法、做做原型开发。但很多朋友在第一步——部署上就卡住了。网上的教程要么太零散要么对系统环境要求说得不清不楚。今天我就基于最常用的Ubuntu 20.04系统带你走一遍完整的部署流程。我的目标很简单就是让你在10分钟左右从零开始把这个模型服务跑起来能正常调用。咱们不扯那些复杂的理论就讲怎么一步步把它装好、启动、然后验证它是不是真的在工作。1. 动手前的准备工作在开始敲命令之前花两分钟检查一下你的“装备”能避免后面一大堆莫名其妙的错误。首先确认你的系统。这篇教程是针对Ubuntu 20.04 LTS写的。你可以在终端里输入下面的命令来查看lsb_release -a看到Description: Ubuntu 20.04.x LTS这样的输出就对了。如果不是有些步骤可能需要调整特别是包管理相关的命令。其次检查一下你的用户权限。很多安装和文件操作需要sudo权限。你可以先试试运行一个需要权限的命令比如sudo ls确保你的账户在sudoers列表里并且知道密码。最后也是最重要的一点网络环境。因为我们需要从网上下载模型文件和一些Python包所以一个稳定、通畅的网络连接是必须的。如果是在公司内网或者有特殊网络策略的环境可能需要提前配置好代理这里指的网络代理设置比如http_proxy环境变量。好了检查完毕咱们就可以进入正题了。2. 系统环境与依赖安装Ubuntu 20.04 自带 Python 3.8这已经满足了我们最基本的需求。但为了后续步骤顺利我们还需要安装一些系统级的工具和开发库。打开你的终端我们一条条命令来过。2.1 更新系统包列表这是个好习惯能确保我们安装的是最新的软件包版本。sudo apt update2.2 安装必要的系统工具和编译依赖这里我们安装一些后续可能会用到的工具比如用于解压的unzip用于版本控制的git以及Python开发所需的头文件和编译工具。sudo apt install -y python3-pip python3-dev git unzip build-essentialpython3-pip: Python的包管理工具后面装Python库全靠它。python3-dev: 包含Python开发需要的头文件有些Python包在编译安装时会用到。git: 万一我们需要从GitHub克隆代码。unzip: 解压压缩包。build-essential: 提供编译C/C代码的基本工具集一些底层依赖可能会用到。2.3 升级pip并设置国内镜像可选但推荐默认的pip源在国外下载速度可能很慢。我们可以把它换成国内的镜像源比如清华的源速度会快很多。pip3 install --upgrade pip pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple执行完这两条命令后续所有pip3 install操作都会从清华镜像站拉取包体验会好不少。3. 获取与准备模型文件SmallThinker-3B-Preview 的模型文件通常托管在模型社区比如 Hugging Face或者一些开源镜像站。这里我们假设从一个公开的URL下载。3.1 创建项目目录并进入我们先找个地方安放我们的模型和代码。我习惯在用户目录下创建一个projects文件夹来管理这些。mkdir -p ~/projects/smallthinker_deploy cd ~/projects/smallthinker_deploy3.2 下载模型文件你需要找到 SmallThinker-3B-Preview 模型权重文件的真实下载链接。这里我用一个示例命令格式你需要替换[模型文件下载链接]为实际的链接。wget [模型文件下载链接] -O model_files.zip注意模型文件可能比较大几个GB请耐心等待下载完成。如果下载中断可以使用wget -c命令来断点续传。3.3 解压模型文件假设下载下来的是一个zip包。unzip model_files.zip -d ./model解压后你的目录结构看起来应该是这样的~/projects/smallthinker_deploy/ ├── model_files.zip └── model/ ├── config.json ├── pytorch_model.bin ├── tokenizer.json └── ... (其他模型文件)model文件夹里应该包含模型配置文件、权重文件、分词器文件等。4. 部署与启动模型服务模型文件准备好了接下来就是写一个简单的服务脚本来加载模型并对外提供API。这里我们用最流行的FastAPI框架来快速搭建一个Web服务用transformers库来加载模型。4.1 安装Python依赖库在我们的项目目录下创建一个requirements.txt文件并填入以下内容fastapi0.104.0 uvicorn[standard]0.24.0 transformers4.35.0 torch2.0.0 sentencepiece0.1.99 # 某些分词器可能需要 pydantic2.0.0然后安装它们pip3 install -r requirements.txt这个安装过程可能会花点时间特别是安装torch的时候。如果系统有NVIDIA GPU并且已经装好了CUDApip通常会安装对应的GPU版本torch这样模型推理会快很多。如果是纯CPU环境安装的就是CPU版本。4.2 编写模型服务脚本创建一个名为app.py的文件这是我们的主服务文件。# app.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from transformers import AutoModelForCausalLM, AutoTokenizer import torch import uvicorn # 定义请求体的数据结构 class PromptRequest(BaseModel): prompt: str max_new_tokens: int 128 temperature: float 0.7 top_p: float 0.9 # 初始化FastAPI应用 app FastAPI(titleSmallThinker-3B-Preview API) # 全局变量用于存放加载的模型和分词器 model None tokenizer None app.on_event(startup) async def load_model(): 服务启动时加载模型 global model, tokenizer try: print(正在加载分词器...) # 请将 ./model 替换为你的模型文件实际路径 tokenizer AutoTokenizer.from_pretrained(./model, trust_remote_codeTrue) print(正在加载模型...这可能需要几分钟请耐心等待...) model AutoModelForCausalLM.from_pretrained( ./model, torch_dtypetorch.float16 if torch.cuda.is_available() else torch.float32, device_mapauto, # 自动分配设备GPU/CPU trust_remote_codeTrue ) print(模型加载完成) if torch.cuda.is_available(): print(f模型已加载至 GPU: {torch.cuda.get_device_name(0)}) else: print(模型运行在 CPU 上。) except Exception as e: print(f模型加载失败: {e}) raise e app.get(/) async def root(): 根路径返回服务状态 return { status: running, model: SmallThinker-3B-Preview, device: cuda if torch.cuda.is_available() else cpu } app.post(/generate/) async def generate_text(request: PromptRequest): 文本生成接口 if model is None or tokenizer is None: raise HTTPException(status_code503, detail模型未就绪) try: # 将输入文本编码为模型可理解的token inputs tokenizer(request.prompt, return_tensorspt).to(model.device) # 使用模型生成文本 with torch.no_grad(): outputs model.generate( **inputs, max_new_tokensrequest.max_new_tokens, temperaturerequest.temperature, top_prequest.top_p, do_sampleTrue, # 启用采样使输出更多样化 pad_token_idtokenizer.eos_token_id ) # 解码生成的token为文本 generated_text tokenizer.decode(outputs[0], skip_special_tokensTrue) # 移除输入提示部分只返回新生成的内容 response_text generated_text[len(request.prompt):].strip() return {generated_text: response_text} except Exception as e: raise HTTPException(status_code500, detailf生成过程中出错: {str(e)}) if __name__ __main__: # 启动服务监听所有网络接口的8000端口 uvicorn.run(app, host0.0.0.0, port8000)脚本要点说明load_model函数会在服务启动时自动调用加载我们放在./model目录下的模型。device_map”auto”会让transformers库自动判断是否有GPU并尝试将模型加载到GPU上这对大模型推理速度至关重要。我们定义了两个接口/用于检查服务状态/generate/是核心的文本生成接口。请务必将代码中的”./model”替换成你实际解压模型文件的完整绝对路径比如”/home/yourname/projects/smallthinker_deploy/model”这样更保险。4.3 启动模型服务保存好app.py后在终端里直接运行它cd ~/projects/smallthinker_deploy python3 app.py如果一切顺利你会看到类似下面的输出先是加载分词器和模型的信息最后一行显示服务已经启动。正在加载分词器... 正在加载模型...这可能需要几分钟请耐心等待... 模型加载完成 模型已加载至 GPU: NVIDIA GeForce RTX 4090 INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRLC to quit)看到Uvicorn running on http://0.0.0.0:8000就成功了你的模型服务现在正在本机的8000端口上运行。5. 验证服务与简单测试服务跑起来了但我们得确认它真的能“干活”。这里我们用最直接的两种方法测试。5.1 方法一用浏览器或curl检查状态打开你的浏览器访问http://你的服务器IP地址:8000。如果你就在运行服务的这台机器上可以直接访问http://localhost:8000或http://127.0.0.1:8000。你应该能看到一个JSON响应{status:running,model:SmallThinker-3B-Preview,device:cuda}这说明基础服务是正常的。5.2 方法二调用生成接口进行真实测试打开另一个终端窗口或者使用curl命令来测试文本生成功能。我们让模型写一句关于“人工智能”的话。curl -X POST http://localhost:8000/generate/ \ -H Content-Type: application/json \ -d { prompt: 请用一句话解释人工智能, max_new_tokens: 50, temperature: 0.8 }如果成功你会收到一个包含generated_text字段的JSON响应里面就是模型生成的句子。第一次调用可能会慢一点因为模型需要做初始化准备。你也可以用Python写个简单的测试脚本test_client.py# test_client.py import requests import json url http://localhost:8000/generate/ headers {Content-Type: application/json} data { prompt: 夏天的特点是, max_new_tokens: 30, temperature: 0.7 } response requests.post(url, headersheaders, datajson.dumps(data)) if response.status_code 200: result response.json() print(模型回复, result[generated_text]) else: print(请求失败:, response.status_code, response.text)运行这个脚本看看模型会不会告诉你夏天是炎热、充满阳光的。6. 可能遇到的问题与解决办法部署过程很少一帆风顺这里列举几个常见问题帮你快速排错。问题1pip install安装包特别慢或者失败。原因网络连接问题或默认源速度慢。解决就像我们前面做的设置国内镜像源清华、阿里云等。如果公司内网需要代理请配置好http_proxy和https_proxy环境变量。问题2启动app.py时提示Port 8000 is already in use。原因8000端口被其他程序可能是你之前启动的另一个服务占用了。解决有两种方法。一是关掉占用8000端口的程序可以用sudo lsof -i:8000查一下是什么进程。二是在app.py里修改uvicorn.run(app, host”0.0.0.0″, port8000)这一行把8000换成其他没被占用的端口号比如8001。问题3模型加载到一半报错提示CUDA out of memory。原因这是最典型的问题说明你的GPU显存不够加载整个3B参数的模型。解决降低精度在app.py的load_model函数里将torch_dtypetorch.float16改为torch_dtypetorch.float32甚至torch_dtypetorch.bfloat16如果硬件支持。半精度float16比单精度float32省一半显存。使用CPU如果GPU显存实在太小可以强制使用CPU。将device_map”auto”改为device_map”cpu”并将torch_dtype设为torch.float32。缺点是推理速度会慢很多。量化加载这是更高级的省显存方法。修改加载模型的代码使用bitsandbytes库进行4位或8位量化这需要额外安装bitsandbytes库。问题4访问http://localhost:8000时连接被拒绝。原因服务可能没有成功启动或者防火墙阻止了端口访问。解决首先确认服务进程是否在运行检查启动app.py的终端有没有报错。如果是云服务器请检查安全组规则是否放行了8000端口或你修改后的端口。在服务器上尝试运行curl http://localhost:8000如果本地能通但外部不通基本就是防火墙或安全组的问题。问题5调用生成接口返回错误比如503: 模型未就绪。原因模型还没加载完请求就过来了。解决等待服务启动完成看到“模型加载完成”和“Application startup complete.”的日志后再进行测试。7. 总结与后续跟着上面这些步骤走下来你应该已经成功在Ubuntu 20.04上把SmallThinker-3B-Preview跑起来了。整个过程的核心其实就是三步准备好系统和Python环境、拿到模型文件、写个简单的服务脚本把它跑起来并对外提供接口。这个用FastAPI写的服务脚本虽然简单但五脏俱全有了它你就可以开始用代码和模型对话了。你可以基于这个基础去扩展更多功能比如添加对话历史管理、支持流式输出一个字一个字地返回、或者做个简单的Web界面。部署本身不是目的只是一个开始。模型跑起来之后你可以多试试不同的提示词prompt看看它在哪些任务上表现好哪些地方还有不足。3B的模型在创意写作、简单问答、代码补全这些任务上应该能给你一些惊喜但对于复杂的逻辑推理或者需要大量知识的任务可能就需要你多花点心思去设计提示词了。最后记得这个服务目前是在前台运行的关掉终端服务就停了。如果你打算长期使用可以考虑用systemd或者supervisor这样的工具把它做成一个后台服务或者用nohup命令让它在后台运行。这些就是后话了先把模型玩起来再说吧。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。