小白友好：Qwen1.5-0.5B-Chat模型API快速调用教程

小白友好：Qwen1.5-0.5B-Chat模型API快速调用教程

1. 教程目标与适用人群

本教程旨在为零基础或初学者提供一份完整、可操作的指南，帮助你在本地环境中快速部署并调用Qwen1.5-0.5B-Chat模型的API服务。无论你是否有Python背景，只要按照步骤操作，即可成功运行一个支持对话和流式响应的大模型服务。

学习目标

• 掌握基于ModelScope生态部署轻量级大模型的基本流程
• 理解如何将本地模型封装为标准RESTful API接口
• 实现同步与流式（streaming）两种模式的API调用
• 获得可复用的代码模板用于后续项目集成

前置要求

• 操作系统：Windows 10/11 或 Linux/macOS
• 内存：建议 ≥ 4GB（模型运行时占用约1.8GB）
• Python基础：无需深入理解，但需会基本命令行操作
• 硬件：无需GPU，纯CPU环境即可运行

2. 环境准备与依赖安装

2.1 安装Anaconda（推荐方式）

为了更好地管理Python环境和依赖包，我们使用Anaconda作为包管理工具。

1. 访问 清华大学开源软件镜像站 下载适用于你系统的Anaconda安装包。
2. 安装过程中选择“Add Anaconda to my PATH”（若未勾选，则需手动配置环境变量）。
3. 安装完成后重启终端或电脑，确保conda命令可用。

验证安装：

conda --version

2.2 创建独立虚拟环境

避免依赖冲突，创建专用环境：

conda create --name qwen_env python=3.10 conda activate qwen_env

2.3 更换国内源以加速下载

执行以下命令生成.condarc配置文件：

conda config --set show_channel_urls yes

然后在用户目录下找到.condarc文件，替换内容如下：

channels: - defaults show_channel_urls: true default_channels: - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2 custom_channels: conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud

清除缓存使配置生效：

conda clean -i

3. 模型下载与本地部署

3.1 下载Qwen1.5-0.5B-Chat模型

该模型是通义千问系列中参数量最小（5亿）且专为对话优化的版本，适合低资源设备部署。

使用Git从ModelScope社区克隆模型：

git clone https://www.modelscope.cn/qwen/Qwen1.5-0.5B-Chat.git

⚠️ 注意：首次使用需登录ModelScope账号并安装modelscope库（见下一步）

如果你遇到权限问题，请先安装ModelScope客户端并登录：

pip install modelscope modelscope login

3.2 安装核心依赖库

在激活的虚拟环境中依次安装所需库：

# 安装PyTorch CPU版（无GPU也可运行） conda install pytorch torchvision torchaudio cpuonly -c pytorch # 安装HuggingFace Transformers及辅助库 pip install transformers accelerate # 安装FastAPI及相关组件 pip install fastapi uvicorn sse_starlette

4. 构建API服务：从零搭建Web接口

我们将使用FastAPI + Uvicorn构建高性能异步API服务，并支持CORS跨域请求。

4.1 基础API框架搭建

新建app.py文件，编写最简API服务：

from fastapi import FastAPI app = FastAPI(title="Qwen1.5-0.5B-Chat API") @app.get("/") def home(): return {"message": "Qwen1.5-0.5B-Chat API is running!"}

启动服务：

uvicorn app:home --reload --host 0.0.0.0 --port 8000

访问http://localhost:8000可看到返回信息。

4.2 加载模型并初始化tokenizer

修改代码，加入模型加载逻辑：

from contextlib import asynccontextmanager import torch from transformers import AutoModelForCausalLM, AutoTokenizer from fastapi import FastAPI @asynccontextmanager async def lifespan(app: FastAPI): # 启动时加载模型 app.state.tokenizer = AutoTokenizer.from_pretrained("Qwen1.5-0.5B-Chat") app.state.model = AutoModelForCausalLM.from_pretrained( "Qwen1.5-0.5B-Chat", device_map="auto", # 自动分配设备 torch_dtype=torch.float32 # CPU推理使用float32 ) yield # 关闭时释放显存（如有） if torch.cuda.is_available(): torch.cuda.empty_cache()

更新主应用：

app = FastAPI(lifespan=lifespan) @app.get("/") def home(): return {"status": "running", "model": "Qwen1.5-0.5B-Chat"}

5. 实现标准对话API接口

5.1 定义请求与响应数据结构

遵循OpenAI风格API设计，定义Pydantic模型：

from pydantic import BaseModel from typing import List, Optional, Literal class ChatMessage(BaseModel): role: Literal["user", "assistant", "system"] content: str class ChatCompletionRequest(BaseModel): model: str = "qwen-0.5b-chat" messages: List[ChatMessage] stream: bool = False class ChatCompletionResponseChoice(BaseModel): index: int message: ChatMessage finish_reason: Literal["stop", "length"] class ChatCompletionResponse(BaseModel): model: str object: Literal["chat.completion"] = "chat.completion" choices: List[ChatCompletionResponseChoice]

5.2 实现同步对话接口

添加POST接口处理函数：

@app.post("/v1/chat/completions", response_model=ChatCompletionResponse) async def chat_completions(request: ChatCompletionRequest): tokenizer = app.state.tokenizer model = app.state.model # 格式化输入 prompt = tokenizer.apply_chat_template( request.messages, tokenize=False, add_generation_prompt=True ) inputs = tokenizer([prompt], return_tensors="pt").to(model.device) # 生成回复 outputs = model.generate( inputs.input_ids, max_new_tokens=512, do_sample=True, temperature=0.7, top_p=0.9 ) # 解码输出 response_text = tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True) choice = ChatCompletionResponseChoice( index=0, message=ChatMessage(role="assistant", content=response_text), finish_reason="stop" ) return ChatCompletionResponse(model=request.model, choices=[choice])

6. 支持流式输出（Streaming）

流式响应能提升用户体验，尤其在长文本生成场景。

6.1 引入TextIteratorStreamer

利用Transformers内置的流式工具类：

from threading import Thread from transformers import TextIteratorStreamer from sse_starlette.sse import EventSourceResponse

6.2 实现流式生成接口

新增异步生成器函数：

async def generate_stream(inputs, model, tokenizer, request_model: str): streamer = TextIteratorStreamer( tokenizer, skip_prompt=True, skip_special_tokens=True ) generation_kwargs = { "input_ids": inputs.input_ids, "max_new_tokens": 512, "do_sample": True, "temperature": 0.7, "top_p": 0.9, "streamer": streamer } thread = Thread(target=model.generate, kwargs=generation_kwargs) thread.start() # 发送开始事件 yield { "data": { "model": request_model, "choices": [{ "index": 0, "delta": {"role": "assistant"}, "finish_reason": None }] } } # 逐段发送生成内容 for text in streamer: if text.strip(): yield { "data": { "model": request_model, "choices": [{ "index": 0, "delta": {"content": text}, "finish_reason": None }] } } # 结束标记 yield { "data": { "model": request_model, "choices": [{ "index": 0, "delta": {}, "finish_reason": "stop" }] } } yield "[DONE]"

6.3 修改主接口支持stream参数

在原有/v1/chat/completions接口中增加判断：

@app.post("/v1/chat/completions") async def chat_completions(request: ChatCompletionRequest): tokenizer = app.state.tokenizer model = app.state.model prompt = tokenizer.apply_chat_template( request.messages, tokenize=False, add_generation_prompt=True ) inputs = tokenizer([prompt], return_tensors="pt").to(model.device) if request.stream: return EventSourceResponse( generate_stream(inputs, model, tokenizer, request.model) ) # 否则走同步逻辑（同上节） ...

7. 测试API接口

7.1 使用curl测试同步请求

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-0.5b-chat", "messages": [ {"role": "user", "content": "请介绍一下你自己"} ], "stream": false }'

7.2 测试流式请求

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-0.5b-chat", "messages": [ {"role": "user", "content": "讲一个关于AI的笑话"} ], "stream": true }'

你会看到内容逐步返回，类似SSE事件流。

8. 总结

通过本教程，你已经完成了以下关键能力构建：

1. ✅ 成功部署了Qwen1.5-0.5B-Chat轻量级对话模型
2. ✅ 构建了一个符合OpenAI API规范的本地服务接口
3. ✅ 实现了同步与流式两种响应模式
4. ✅ 掌握了FastAPI+Transformers组合开发的基本范式

该方案特别适合以下场景： - 本地私有化部署，保障数据安全 - 边缘设备或低配服务器运行 - 快速原型验证与产品集成测试

未来你可以在此基础上扩展更多功能，如： - 添加身份认证（JWT/Bearer Token） - 集成向量数据库实现RAG增强回答 - 包装为Docker镜像便于分发 - 对接前端Web界面形成完整应用

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。