手把手教学：基于Streamlit的DeepSeek-R1聊天界面开发

手把手教学：基于Streamlit的DeepSeek-R1聊天界面开发

1. 为什么选Streamlit做这个聊天界面？

1.1 你可能正面临这些实际问题

你刚下载好 DeepSeek-R1-Distill-Qwen-1.5B 这个轻量又聪明的模型，但卡在了最后一步——怎么让它真正“用起来”？
不是所有人都习惯敲命令行，也不是每个团队都有前端工程师来搭页面。你可能试过直接调用model.generate()，结果输出一堆带<think>标签的原始文本，看着费劲；也可能想加个清空按钮，却发现每次重置都要手动删历史、清显存，一不小心就 OOM；更别说多轮对话上下文拼接出错、思考过程和答案混在一起、公式代码没法高亮……这些细节，才是真正影响使用体验的关键。

而 Streamlit 就是为这类场景而生的：它不强迫你写 HTML/CSS/JS，不用配路由、建后端、搞跨域，几行 Python 就能跑出一个像模像样的 Web 聊天页——输入框在底下，消息气泡从上往下堆，左侧边栏放控制按钮，所有逻辑都在一个.py文件里，改完保存自动刷新。对本地模型开发者来说，它不是“另一个框架”，而是把模型能力直接递给使用者的那双手。

1.2 和 Gradio 比，Streamlit 到底强在哪？

别误会，Gradio 很好，但它更像一个“功能完备的工具箱”——组件丰富、参数可调、支持流式、能上 Hugging Face Spaces。而 Streamlit 更像一把“开箱即用的瑞士军刀”：轻、快、原生适配 Python 生态，尤其适合以模型为中心、界面为辅、追求极简交付的本地部署场景。

一句话总结：如果你的目标是——让模型能力零门槛落地，而不是搭建一个可扩展的 AI 平台，Streamlit 是更干净、更省心的选择。

1.3 本教程你能真正掌握什么

这不是一个“复制粘贴就能跑”的模板教程，而是一次带你从原理到工程细节的完整拆解：

• 理解为什么st.cache_resource能让模型秒级响应，以及它和st.cache_data的本质区别
• 掌握如何用tokenizer.apply_chat_template正确拼接多轮对话，避免“答非所问”或“重复输出前文”
• 学会自动识别并格式化模型输出中的<think>和</think>标签，把原始 token 流变成结构清晰的「思考过程 + 最终回答」
• 实现一键清空：不只是清聊天记录，更是同步释放 GPU 显存，防止多次对话后显存堆积溢出
• 看懂device_map="auto"和torch_dtype="auto"如何智能适配你的硬件（哪怕只有一块 RTX 3060）

学完，你不仅能跑起这个界面，更能把它迁移到其他本地模型上——这才是真正的可复用能力。

2. 环境准备与模型加载

2.1 最小依赖清单（不装多余包）

我们坚持“够用就好”原则。整个项目只需 4 个核心依赖，全部来自 PyPI 官方源，无需魔塔平台或私有镜像：

pip install torch==2.4.0+cu121 transformers==4.45.2 accelerate==1.2.1 streamlit==1.38.0 -f https://download.pytorch.org/whl/torch_stable.html

注意：CUDA 版本必须匹配你的驱动。若你用的是 CPU 或 AMD GPU，请替换为：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

不需要bitsandbytes、不需要vLLM、不需要llama.cpp——因为 DeepSeek-R1-Distill-Qwen-1.5B 本身已足够轻量，1.5B 参数在 FP16 下仅需约 1.7GB 显存，RTX 3060（12GB）或 A10（24GB）均可流畅运行。

2.2 模型路径确认与加载策略

镜像文档明确指出：模型文件位于/root/ds_1.5b。这是关键前提，所有后续操作都基于此路径。

我们采用双重加载保障机制：

• 第一层：st.cache_resource缓存模型与分词器
  确保服务启动后只加载一次，后续所有用户会话共享同一份模型实例，避免重复初始化导致的 20 秒等待。

• 第二层：trust_remote_code=True+local_files_only=True
  强制跳过网络请求，只读本地文件；同时允许加载魔塔平台特有的蒸馏模型结构（含自定义Qwen2ForCausalLM和推理优化逻辑）。

import streamlit as st from transformers import AutoTokenizer, AutoModelForCausalLM import torch @st.cache_resource def load_model(): model_path = "/root/ds_1.5b" # 加载分词器（自动识别 chat template） tokenizer = AutoTokenizer.from_pretrained( model_path, trust_remote_code=True, use_fast=True ) # 加载模型（自动选择设备与精度） model = AutoModelForCausalLM.from_pretrained( model_path, trust_remote_code=True, torch_dtype="auto", # 自动选 float16 / bfloat16 / float32 device_map="auto", # 自动分配 GPU/CPU 层 local_files_only=True # 绝不联网 ) return tokenizer, model tokenizer, model = load_model()

这段代码会在 Streamlit 第一次访问时执行加载，并缓存结果。之后无论刷新多少次、打开多少个浏览器标签，都不会重新加载模型。

2.3 为什么torch_dtype="auto"比硬写float16更稳妥？

很多教程直接写torch_dtype=torch.float16，看似省事，实则埋雷：

• 在某些旧 GPU（如 GTX 10xx 系列）上，float16不被原生支持，强制启用会导致RuntimeError: "addmm_cuda" not implemented for 'Half'
• 在 CPU 模式下，float16无法计算，必须回退为float32

而"auto"会根据当前设备智能决策：

这正是“硬件参数智能适配”的底层实现——你不用操心，它自己懂。

3. 构建聊天界面：从输入到结构化输出

3.1 多轮对话上下文拼接（关键！）

DeepSeek-R1-Distill-Qwen-1.5B 使用标准 Qwen Chat Template，格式为：

<|im_start|>system You are a helpful assistant.<|im_end|> <|im_start|>user 解这道题：<|im_end|> <|im_start|>assistant <|im_start|>think 先整理已知条件……<|im_end|> <|im_start|>assistant 答案是 x=5。<|im_end|>

错误做法：手动拼字符串。极易漏掉<|im_end|>、错位<|im_start|>、破坏 token 对齐，导致模型“听不懂”。

正确做法：交给tokenizer.apply_chat_template，它会严格按模型训练时的格式生成输入：

def build_prompt(messages): # messages 是 [{"role": "user", "content": "..."}, ...] 列表 return tokenizer.apply_chat_template( messages, tokenize=False, # 返回字符串，非 tensor add_generation_prompt=True, # 末尾自动加 <|im_start|>assistant return_tensors=None ) # 示例调用 messages = [ {"role": "system", "content": "你是一个严谨的数学助手"}, {"role": "user", "content": "解方程 2x + 3 = 7"} ] prompt = build_prompt(messages) # 输出：'<|im_start|>system\n你是一个严谨的数学助手<|im_end|>\n<|im_start|>user\n解方程 2x + 3 = 7<|im_end|>\n<|im_start|>assistant\n'

这是保证多轮对话稳定性的基石。只要messages结构正确，prompt就一定合规。

3.2 推理参数配置：为什么是 0.6 和 0.95？

镜像文档强调“思维链推理专属优化”，这直接反映在两个核心采样参数上：

• temperature=0.6：比默认 0.8–1.0 更低，抑制随机性，让模型更“专注”于逻辑推导，减少胡说八道
• top_p=0.95：保留概率累计达 95% 的 top tokens，既过滤掉明显错误的低概率词（如乱码、无关符号），又保留合理多样性（不像top_k=10那样死板）

def generate_response(messages, max_new_tokens=2048, temperature=0.6, top_p=0.95): prompt = build_prompt(messages) inputs = tokenizer(prompt, return_tensors="pt").to(model.device) with torch.no_grad(): outputs = model.generate( **inputs, max_new_tokens=max_new_tokens, temperature=temperature, top_p=top_p, do_sample=True, pad_token_id=tokenizer.eos_token_id, eos_token_id=tokenizer.convert_tokens_to_ids("<|im_end|>") ) full_output = tokenizer.decode(outputs[0], skip_special_tokens=False) # 截取生成部分（去掉 prompt） response = full_output[len(prompt):] return response

注意eos_token_id显式指定为<|im_end|>，这是 Qwen 系列的终止符，不设它可能导致生成无限循环。

3.3 自动格式化解析：把<think>变成可读内容

模型原始输出类似：

<|im_start|>think 设未知数 x，根据题意列出方程：2x + 3 = 7。 移项得：2x = 4。 两边同除以 2：x = 2。<|im_end|> <|im_start|>assistant x = 2

我们需要把它转成：

** 思考过程**
设未知数 x，根据题意列出方程：2x + 3 = 7。
移项得：2x = 4。
两边同除以 2：x = 2。

** 最终回答**
x = 2

实现逻辑很清晰：用正则提取<|im_start|>think和<|im_end|>之间的内容，再提取<|im_start|>assistant后的内容：

import re def parse_thinking_response(raw_text): # 提取思考过程 think_match = re.search(r"<\|im_start\|>think\s*(.*?)<\|im_end\|>", raw_text, re.DOTALL) thinking = think_match.group(1).strip() if think_match else "" # 提取最终回答（取最后一个 <|im_start|>assistant 之后的内容） assistant_parts = re.split(r"<\|im_start\|>assistant", raw_text) answer = assistant_parts[-1].strip() if len(assistant_parts) > 1 else raw_text # 清理残留 token answer = re.sub(r"<\|im_end\|>.*$", "", answer, flags=re.DOTALL).strip() return thinking, answer # 使用示例 thinking, answer = parse_thinking_response(raw_output) if thinking: st.markdown(f"** 思考过程** \n{thinking}") if answer: st.markdown(f"** 最终回答** \n{answer}")

这段解析逻辑嵌入在 Streamlit 主循环中，每次生成后自动执行，用户看到的就是结构化结果，不是原始 token 流。

4. Streamlit 界面实现：一行代码一个功能

4.1 页面布局设计（极简主义）

我们采用经典的三区布局：

• 顶部标题栏：说明模型身份与能力定位
• 中部消息区：气泡式对话流，用户消息靠右，AI 回复靠左，带时间戳与角色标识
• 底部输入区 + 左侧边栏：输入框 + 发送按钮 + 「🧹 清空」按钮

全部用原生 Streamlit 组件实现，无 CSS 注入、无 JS 注入，纯 Python 控制。

# 初始化 session state if "messages" not in st.session_state: st.session_state.messages = [ {"role": "assistant", "content": "你好！我是 DeepSeek-R1，擅长数学推理、代码编写和逻辑分析。请开始提问吧～"} ] # 顶部标题 st.title("🐋 DeepSeek-R1-Distill-Qwen-1.5B 本地智能对话助手") st.caption("全本地运行 · 零数据上传 · 思维链自动解析") # 左侧边栏 with st.sidebar: st.header("⚙ 控制面板") if st.button("🧹 清空对话", use_container_width=True, type="secondary"): st.session_state.messages.clear() st.session_state.messages.append({ "role": "assistant", "content": "对话已清空，GPU 显存已释放。欢迎开启新话题！" }) torch.cuda.empty_cache() # 关键：显存同步清理 st.rerun() # 中部消息区 for msg in st.session_state.messages: with st.chat_message(msg["role"]): st.markdown(msg["content"]) # 底部输入区 if prompt := st.chat_input("考考 DeepSeek R1...（例如：写一段冒泡排序 Python 代码）"): # 添加用户消息 st.session_state.messages.append({"role": "user", "content": prompt}) with st.chat_message("user"): st.markdown(prompt) # 调用模型生成 with st.chat_message("assistant"): with st.spinner("🧠 正在深度思考中..."): response = generate_response(st.session_state.messages) thinking, answer = parse_thinking_response(response) if thinking: st.markdown(f"** 思考过程** \n{thinking}") if answer: st.markdown(f"** 最终回答** \n{answer}") # 保存 AI 回复 st.session_state.messages.append({"role": "assistant", "content": f"{thinking}\n\n{answer}"})

所有交互逻辑都在这个文件里，没有外部状态服务、没有数据库、没有 API 调用——真正的单文件、纯本地、零依赖。

4.2 为什么st.rerun()比st.experimental_rerun()更推荐？

st.experimental_rerun()是旧版 API，已在 Streamlit 1.30+ 中标记为 deprecated。新版st.rerun()是正式替代，语义更清晰，且在st.button点击后立即生效，确保清空操作后界面即时刷新，不会残留旧消息。

4.3 时间戳与角色标识：提升专业感的小细节

虽然 Streamlitst.chat_message默认不带时间，但我们可以通过st.caption()补充：

from datetime import datetime for msg in st.session_state.messages: with st.chat_message(msg["role"]): st.markdown(msg["content"]) st.caption(f"{datetime.now().strftime('%H:%M')} • {msg['role'].upper()}")

这样每条消息下方都显示发送时间与角色，既增强可信度，又方便调试追踪。

5. 部署与稳定性保障

5.1 一键启动命令（无配置文件）

无需config.toml，无需环境变量，直接运行：

streamlit run app.py --server.port=8501 --server.address=0.0.0.0

• --server.port=8501：避开常用端口（8000/8080），减少冲突
• --server.address=0.0.0.0：允许外部访问（内网穿透或云服务器必备）

启动后，终端会打印类似：

You can now view your Streamlit app in your browser. Network URL: http://192.168.1.100:8501 External URL: http://xxx.xxx.xxx.xxx:8501

点击 External URL 即可从其他设备访问。

5.2 Docker 部署精简版（仅 3 行 Dockerfile）

相比 Gradio 教程中复杂的多阶段构建，Streamlit 部署可极致简化：

FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04 RUN apt-get update && apt-get install -y python3-pip && rm -rf /var/lib/apt/lists/* RUN pip install torch==2.4.0+cu121 transformers==4.45.2 accelerate==1.2.1 streamlit==1.38.0 -f https://download.pytorch.org/whl/torch_stable.html COPY app.py / EXPOSE 8501 CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

构建与运行：

docker build -t deepseek-r1-streamlit . docker run -d --gpus all -p 8501:8501 -v /root/ds_1.5b:/root/ds_1.5b deepseek-r1-streamlit

模型路径通过-v挂载，镜像本身不打包模型，体积 < 200MB，拉取快、部署快、更新快。

5.3 显存监控与防溢出策略

即使有torch.no_grad()和empty_cache()，长时间运行仍可能因 PyTorch 缓存累积导致 OOM。我们在app.py开头加入轻量级监控：

def check_gpu_memory(): if torch.cuda.is_available(): free, total = torch.cuda.mem_get_info() usage_pct = (total - free) / total * 100 if usage_pct > 90: st.warning(f" GPU 显存使用率 {usage_pct:.1f}%，建议清空对话释放资源") check_gpu_memory()

放在st.sidebar上方，每次刷新都检查，直观提醒用户何时该点「🧹 清空」。

6. 总结

6.1 你已经掌握的核心能力

回顾整个开发流程，你不再只是“跑通了一个 demo”，而是真正理解并实践了以下关键工程能力：

• 模型加载的确定性：通过st.cache_resource+local_files_only=True，确保每次启动行为一致，杜绝“有时快有时慢”的玄学问题
• 对话协议的严谨性：用apply_chat_template代替字符串拼接，让多轮上下文管理从“可能出错”变为“必然正确”
• 输出解析的实用性：将<think>标签转化为可读结构，不是炫技，而是直击用户理解成本痛点
• 资源管理的完整性：清空按钮 = 清历史 + 清显存 + 刷新界面，三位一体，拒绝半吊子清理
• 部署的极简化：单文件、单命令、单 Dockerfile，把“能用”和“好用”的距离压缩到最小

这些不是孤立技巧，而是一套可迁移的本地大模型应用开发范式。

6.2 下一步可以怎么延伸？

• 增加代码高亮：在st.markdown()渲染前，用re.sub(r'```(\w+)?', r'```python', answer)统一语言标识，触发 Streamlit 自动语法高亮
• 支持 LaTeX 公式：Streamlit 原生支持$E=mc^2$，无需额外配置，数学类回答自动美化
• 添加系统提示词开关：在侧边栏加st.toggle("启用系统指令")，动态控制是否注入system角色
• 导出对话记录：加一个st.download_button，一键下载 Markdown 格式聊天日志

所有这些，都建立在你已掌握的这个坚实基座之上。

获取更多AI镜像

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