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 update

2.2 安装必要的系统工具和编译依赖

这里我们安装一些后续可能会用到的工具，比如用于解压的unzip，用于版本控制的git，以及Python开发所需的头文件和编译工具。

sudo apt install -y python3-pip python3-dev git unzip build-essential

python3-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_deploy

3.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文件，并填入以下内容：

fastapi>=0.104.0 uvicorn[standard]>=0.24.0 transformers>=4.35.0 torch>=2.0.0 sentencepiece>=0.1.99 # 某些分词器可能需要 pydantic>=2.0.0

然后安装它们：

pip3 install -r requirements.txt

这个安装过程可能会花点时间，特别是安装torch的时候。如果系统有NVIDIA GPU并且已经装好了CUDA，pip通常会安装对应的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(title="SmallThinker-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_code=True) print("正在加载模型...这可能需要几分钟，请耐心等待...") model = AutoModelForCausalLM.from_pretrained( "./model", torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32, device_map="auto", # 自动分配设备（GPU/CPU） trust_remote_code=True ) 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_code=503, detail="模型未就绪") try: # 将输入文本编码为模型可理解的token inputs = tokenizer(request.prompt, return_tensors="pt").to(model.device) # 使用模型生成文本 with torch.no_grad(): outputs = model.generate( **inputs, max_new_tokens=request.max_new_tokens, temperature=request.temperature, top_p=request.top_p, do_sample=True, # 启用采样，使输出更多样化 pad_token_id=tokenizer.eos_token_id ) # 解码生成的token为文本 generated_text = tokenizer.decode(outputs[0], skip_special_tokens=True) # 移除输入提示部分，只返回新生成的内容 response_text = generated_text[len(request.prompt):].strip() return {"generated_text": response_text} except Exception as e: raise HTTPException(status_code=500, detail=f"生成过程中出错: {str(e)}") if __name__ == "__main__": # 启动服务，监听所有网络接口的8000端口 uvicorn.run(app, host="0.0.0.0", port=8000)

脚本要点说明：

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 CTRL+C 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, headers=headers, data=json.dumps(data)) if response.status_code == 200: result = response.json() print("模型回复：", result["generated_text"]) else: print("请求失败:", response.status_code, response.text)

运行这个脚本，看看模型会不会告诉你夏天是炎热、充满阳光的。

6. 可能遇到的问题与解决办法

部署过程很少一帆风顺，这里列举几个常见问题，帮你快速排错。

问题1：pip 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″, port=8000)这一行，把8000换成其他没被占用的端口号，比如8001。

问题3：模型加载到一半报错，提示CUDA out of memory。

原因：这是最典型的问题，说明你的GPU显存不够加载整个3B参数的模型。
解决：
1. 降低精度：在app.py的load_model函数里，将torch_dtype=torch.float16改为torch_dtype=torch.float32甚至torch_dtype=torch.bfloat16（如果硬件支持）。半精度（float16）比单精度（float32）省一半显存。
2. 使用CPU：如果GPU显存实在太小，可以强制使用CPU。将device_map=”auto”改为device_map=”cpu”，并将torch_dtype设为torch.float32。缺点是推理速度会慢很多。
3. 量化加载：这是更高级的省显存方法。修改加载模型的代码，使用bitsandbytes库进行4位或8位量化（这需要额外安装bitsandbytes库）。

问题4：访问http://localhost:8000时连接被拒绝。

原因：服务可能没有成功启动，或者防火墙阻止了端口访问。
解决：
1. 首先确认服务进程是否在运行（检查启动app.py的终端有没有报错）。
2. 如果是云服务器，请检查安全组规则是否放行了8000端口（或你修改后的端口）。
3. 在服务器上尝试运行curl http://localhost:8000，如果本地能通但外部不通，基本就是防火墙或安全组的问题。

问题5：调用生成接口返回错误，比如503: 模型未就绪。