Qwen2.5-1.5B Streamlit部署教程：添加API接口供其他系统调用的改造方法-育师

Qwen2.5-1.5B Streamlit部署教程：添加API接口供其他系统调用的改造方法

1. 为什么需要为Streamlit对话应用增加API能力

你已经成功跑起了一个本地Qwen2.5-1.5B聊天界面——界面清爽、响应快、数据不出本地，用起来很安心。但很快你会发现：这个漂亮的Web页面，只服务“人”，不服务“系统”。

比如，你想把AI能力嵌入到公司内部的OA审批流程里，让员工提交报销单时自动补全事由；或者想接入企业微信机器人，让群聊中@机器人就能查知识库；又或者要和低代码平台联动，让表单提交后自动触发文案生成……这些场景，都需要一个可编程调用的接口（API），而不是只能点开浏览器手动聊天。

原生Streamlit是面向终端用户的交互框架，它不提供HTTP API服务。它的核心逻辑是“前端渲染+后端状态管理”，所有推理都在st.session_state里流转，没有对外暴露的REST端点。这就意味着：其他程序根本没法和它说话。

本教程不教你从零重写服务，而是基于你已有的Streamlit项目，做最小侵入式改造——保留原有聊天界面完全不变，同时新增一套独立、稳定、可被任意HTTP客户端调用的API服务。整个过程无需更换模型、不改动推理逻辑、不重装依赖，只需增加不到50行关键代码，就能让本地Qwen2.5-1.5B真正成为你私有AI基础设施中的一个“可插拔模块”。

1.1 改造前 vs 改造后：能力边界彻底打开

维度	改造前（纯Streamlit）	改造后（Streamlit + API）
调用方式	仅限浏览器人工操作	支持curl、Python requests、Postman、Node.js、企业微信/飞书机器人、Zapier等任意HTTP客户端
集成能力	孤立应用，无法嵌入业务流	可作为微服务接入ERP、CRM、BI、低代码平台等现有系统
使用场景	单人临时问答	批量处理（如：每天自动生成100份周报摘要）、自动化触发（如：Git提交后自动写PR描述）、多端统一调用（Web/App/小程序共用同一后端）
部署灵活性	必须启动Streamlit服务才能用	API可独立部署（如用Uvicorn托管），Streamlit前端甚至可关闭，只留API持续运行

这不是功能叠加，而是角色升级：从“玩具级聊天框”变成“生产就绪的AI能力节点”。

2. 核心思路：分离UI层与能力层，复用已有推理逻辑

很多开发者一想到加API，就本能地想“重写后端”，甚至准备上FastAPI或Flask。但这里有个关键认知：你最宝贵的资产不是界面，而是已经调试好的模型加载、上下文管理、生成参数配置和安全处理逻辑。这些在Streamlit代码里早已稳定运行。

我们的策略是：不动模型加载和推理主干，只把“输入→模型→输出”这一核心链路抽离成可复用函数，并用轻量HTTP服务器包裹它。

具体分三步走：

第一步：将Streamlit中负责“接收用户输入→调用模型→返回回复”的核心逻辑，封装成一个干净、无UI依赖的Python函数；
第二步：用Uvicorn（ASGI服务器）托管一个FastAPI应用，该应用只做一件事：接收HTTP请求，调用上一步封装的函数，返回JSON响应；
第三步：保持原有Streamlit应用完全不动，让它继续服务人类用户；新API服务则并行运行，服务机器用户。

整个架构清晰解耦：
[用户浏览器] ←→ [Streamlit UI]
[其他系统] ←→ [FastAPI API] ←→ [共享推理函数] ←→ [Qwen2.5-1.5B模型]

所有GPU资源、模型缓存、分词器实例都由同一个Python进程管理，零重复加载，显存占用不增加。

3. 实操步骤：5分钟完成API改造

前提确认：你已按原项目说明，在/root/qwen1.5b路径下完整存放Qwen2.5-1.5B-Instruct模型文件，并能正常运行Streamlit聊天界面。

3.1 创建独立API模块：`api_server.py`

在你的项目根目录（即app.py所在位置）新建文件api_server.py，内容如下：

# api_server.py import os import torch from transformers import AutoTokenizer, AutoModelForCausalLM, TextIteratorStreamer from threading import Thread from fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import List, Optional # === 复用原Streamlit的模型加载逻辑（精简版）=== MODEL_PATH = "/root/qwen1.5b" tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_code=True) model = AutoModelForCausalLM.from_pretrained( MODEL_PATH, device_map="auto", torch_dtype="auto", trust_remote_code=True ) model.eval() # === 封装核心推理函数（关键！）=== def chat_with_qwen( messages: List[dict], max_new_tokens: int = 1024, temperature: float = 0.7, top_p: float = 0.9, do_sample: bool = True ) -> str: """ 纯文本对话推理函数，完全复用原项目逻辑 messages: [{"role": "user", "content": "你好"}, {"role": "assistant", "content": "你好！"}] 返回纯文本回复 """ # 使用官方聊天模板拼接上下文 text = tokenizer.apply_chat_template( messages, tokenize=False, add_generation_prompt=True ) model_inputs = tokenizer([text], return_tensors="pt").to(model.device) with torch.no_grad(): outputs = model.generate( **model_inputs, max_new_tokens=max_new_tokens, temperature=temperature, top_p=top_p, do_sample=do_sample, pad_token_id=tokenizer.eos_token_id, eos_token_id=tokenizer.eos_token_id ) response = tokenizer.decode(outputs[0][model_inputs.input_ids.shape[1]:], skip_special_tokens=True) return response.strip() # === FastAPI应用 === app = FastAPI( title="Qwen2.5-1.5B Local API", description="基于Qwen2.5-1.5B-Instruct的本地化文本生成API，支持多轮对话上下文", version="1.0" ) class ChatRequest(BaseModel): messages: List[dict] max_new_tokens: Optional[int] = 1024 temperature: Optional[float] = 0.7 top_p: Optional[float] = 0.9 class ChatResponse(BaseModel): reply: str @app.post("/v1/chat/completions", response_model=ChatResponse) async def chat_completions(request: ChatRequest): try: reply = chat_with_qwen( messages=request.messages, max_new_tokens=request.max_new_tokens, temperature=request.temperature, top_p=request.top_p ) return {"reply": reply} except Exception as e: raise HTTPException(status_code=500, detail=f"推理失败: {str(e)}") @app.get("/health") async def health_check(): return {"status": "ok", "model": "Qwen2.5-1.5B-Instruct", "device": str(model.device)}

关键点说明：

chat_with_qwen()函数完全复用原Streamlit中st.cache_resource加载后的tokenizer和model，确保行为100%一致；
输入messages格式严格对齐OpenAI API规范（[{"role":"user","content":"..."}]），方便未来无缝迁移；
/health端点用于健康检查，运维监控必备；
所有异常捕获并返回标准HTTP错误，便于调用方处理。

3.2 安装轻量依赖

在项目环境中执行（仅需一次）：

pip install fastapi uvicorn python-multipart

注意：uvicorn是ASGI服务器，比传统WSGI更轻更快，完美适配大模型推理的异步IO特性；python-multipart用于后续可能的文件上传扩展（如图生文），当前非必需但建议安装。

3.3 启动API服务

在终端中运行：

uvicorn api_server:app --host 0.0.0.0 --port 8000 --workers 1 --reload

--host 0.0.0.0：允许局域网内其他设备访问（如手机、同事电脑）；
--port 8000：API服务端口，与Streamlit默认的8501端口不冲突；
--workers 1：大模型推理是CPU/GPU密集型，多进程反而争抢显存，单worker最稳；
--reload：开发时启用热重载，改代码后自动重启（上线请移除）。

启动成功后，你会看到类似日志：

INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) INFO: Started reloader process [12345] INFO: Started server process [12346] INFO: Waiting for application startup. INFO: Application startup complete.

此时API已就绪！打开浏览器访问http://localhost:8000/health，应返回{"status":"ok",...}。

4. 测试API：三种最常用调用方式

别急着写业务代码，先亲手验证API是否真正可用。以下测试均在本地执行，无需额外工具。

4.1 使用curl（Linux/macOS终端或Windows PowerShell）

curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "messages": [ {"role": "user", "content": "用一句话解释量子纠缠"} ], "max_new_tokens": 256 }'

成功响应示例：

{"reply":"量子纠缠是指两个或多个粒子在相互作用后形成一种特殊关联状态，即使相隔遥远，对其中一个粒子的测量会瞬间影响另一个粒子的状态，这种关联无法用经典物理理论解释。"}

4.2 使用Python requests（适合集成进脚本）

新建test_api.py：

import requests url = "http://localhost:8000/v1/chat/completions" data = { "messages": [ {"role": "user", "content": "写一首关于春天的五言绝句"} ] } response = requests.post(url, json=data) if response.status_code == 200: print(" AI回复：", response.json()["reply"]) else: print("❌ 请求失败：", response.text)

运行python test_api.py，立即看到AI生成的古诗。

4.3 使用Postman（可视化调试，推荐给非程序员）

新建Request，Method选POST，URL填http://localhost:8000/v1/chat/completions；
切换到Body→raw→JSON，粘贴上述curl中的JSON数据；
点击Send，右侧立刻显示格式化JSON响应。

小技巧：在Postman中保存这个请求为集合，以后每次重启API只需点一下Send，5秒验证服务状态。

5. 进阶实践：让API真正融入你的工作流

API跑通只是起点。下面两个真实场景，展示如何把它变成生产力工具。

5.1 场景一：企业微信机器人自动答疑

假设你公司知识库存在Confluence，你想让员工在企微群里@机器人提问，自动返回答案。

只需在企微机器人后台配置「接收消息」URL为http://你的服务器IP:8000/v1/chat/completions（需内网穿透或部署在公网服务器），然后用以下Python伪代码处理：

# 企微收到消息后，提取text字段，构造messages messages = [ {"role": "system", "content": "你是一个技术文档助手，请基于提供的知识库片段回答问题，不要编造信息。"}, {"role": "user", "content": "企微用户发送的问题文本"} ] # 调用本地API response = requests.post("http://localhost:8000/v1/chat/completions", json={"messages": messages}) ai_reply = response.json()["reply"] # 将ai_reply发回企微群 send_to_wecom_group(ai_reply)

效果：员工不再需要切出微信去打开浏览器，提问-回答全程在群内闭环。

5.2 场景二：自动化周报生成（定时任务）

每周一上午9点，自动汇总上周Git提交记录，生成团队周报摘要。

用cron（Linux）或Task Scheduler（Windows）定时执行：

# 每周一9点执行 0 9 * * 1 curl -s "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{"messages":[{"role":"user","content":"根据以下Git提交记录，生成一份简洁的团队技术周报摘要（200字以内）：$(git log --oneline -n 20 --since=\"last week\")"}]}' \ | jq -r '.reply' > /home/user/reports/weekly_$(date +%Y%m%d).md

效果：从此告别手动写周报，AI帮你提炼重点，你只需花2分钟审阅。

6. 关键注意事项与避坑指南

API虽小，但涉及模型、网络、并发，几个细节没注意就会卡住：

❌不要用--reload上线：开发时方便，但模型加载后热重载会引发CUDA context错误。生产环境启动命令去掉--reload，并用nohup或systemd守护进程；
❌避免多worker争抢GPU：uvicorn --workers N（N>1）会导致每个worker都尝试加载模型到GPU，显存直接爆满。务必保持--workers 1；
显存清理已内置：torch.no_grad()+model.eval()已确保推理时不占梯度显存；若需长期运行，可在chat_with_qwen()末尾加torch.cuda.empty_cache()（仅GPU环境）；
跨域问题？不用管：本API默认不设CORS，因为它是供后端系统调用（非浏览器直连）。如果你真要用JS前端调用，加一行from fastapi.middleware.cors import CORSMiddleware并配置即可；
安全性兜底：当前API无鉴权，仅限内网使用。如需公网暴露，务必在反向代理（Nginx）层加Basic Auth，或在FastAPI中集成OAuth2。

7. 总结：你已掌握本地大模型API化的通用范式

回顾整个过程，你并没有学习新模型、没有重写推理代码、没有折腾CUDA版本——你只是做了一件极简单却极关键的事：把“能做事”的逻辑，从“给人看的界面”里摘出来，包装成“给机器用的语言”。

这套方法论可100%迁移到其他本地模型：

换成Phi-3-mini？只需改MODEL_PATH和AutoTokenizer.from_pretrained(...)两处；
换成DeepSeek-Coder-1.3B？同样只改模型路径，apply_chat_template换成对应方法；
想支持图片输入？在chat_with_qwen()里加入transformers.AutoProcessor，再扩展API参数即可。

真正的技术价值，不在于炫技跑通某个模型，而在于构建可复用、可组合、可演进的能力基座。今天你为Qwen2.5-1.5B加上的这组API，明天就能成为你私有AI平台的第一块基石。

现在，关掉这个教程页面，打开你的终端，敲下那行uvicorn api_server:app --host 0.0.0.0 --port 8000——几秒后，属于你自己的本地AI能力，正式上线。

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

Qwen2.5-1.5B Streamlit部署教程：添加API接口供其他系统调用的改造方法