Nanbeige 4.1-3B Streamlit WebUI实战教程：适配多模型Chat Template方案

优质文章学习记录

06 Apr 2026 — 13 min read

Nanbeige 4.1-3B Streamlit WebUI实战教程：适配多模型Chat Template方案

1. 引言：从零打造一个专属的AI聊天室

如果你用过一些开源大模型，可能会发现一个痛点：官方提供的Web界面要么太简陋，要么配置复杂。今天，我们就来解决这个问题。

我将带你一步步搭建一个专为Nanbeige 4.1-3B模型设计的Web聊天界面。这不仅仅是一个界面，而是一个可以轻松适配其他模型的通用方案。整个项目只有一个Python文件，不需要懂前端框架，用纯Python就能做出媲美专业聊天应用的视觉效果。

想象一下，你可以在本地电脑上运行一个界面清爽、响应迅速的AI对话应用，还能根据不同的模型自动调整对话格式。这就是我们今天要实现的。

2. 项目核心亮点：为什么选择这个方案

在开始动手之前，我们先看看这个方案有哪些吸引人的地方。

2.1 极简现代的视觉设计

传统的Streamlit应用往往有固定的侧边栏和方方正正的布局，看起来比较呆板。我们这个方案通过CSS彻底改变了这一点。

聊天气泡布局：用户消息在右侧（天蓝色背景），AI回复在左侧（白色背景），就像手机短信应用一样自然。
清爽的背景：采用了浅灰蓝色搭配极简圆点网格，长时间使用也不会视觉疲劳。
智能折叠设计：对于支持深度思考（Chain-of-Thought）的模型，思考过程会自动折叠起来，保持主界面的整洁。

2.2 技术实现的巧妙之处

这个项目的技术方案有几个值得关注的亮点：

纯Python实现：不需要React、Vue等前端框架，所有界面逻辑都在一个Python文件中完成。
CSS魔法：通过:has()伪类选择器实现了动态布局判断，这是Streamlit原生组件做不到的。
流式输出优化：基于TextIteratorStreamer实现打字机效果，配合防抖CSS确保界面不闪烁。

2.3 强大的扩展性

虽然我们以Nanbeige 4.1-3B为例，但这个框架设计时就考虑到了多模型适配。你只需要修改少量代码，就能让它支持Qwen、Llama、ChatGLM等各种开源模型。

3. 环境准备与快速部署

3.1 安装必要的软件包

首先确保你的Python环境是3.10或更高版本。打开终端，运行以下命令安装依赖：

pip install streamlit torch transformers accelerate

这几个包的作用分别是：

streamlit：构建Web界面的核心框架
torch：PyTorch深度学习框架
transformers：Hugging Face的模型加载和推理库
accelerate：优化模型加载和推理速度

3.2 下载模型权重

你需要先下载Nanbeige 4.1-3B的模型文件。有两种方式：

方式一：从Hugging Face直接下载

from transformers import AutoModelForCausalLM, AutoTokenizer model_name = "Nanbeige/Nanbeige4-3B" model = AutoModelForCausalLM.from_pretrained(model_name) tokenizer = AutoTokenizer.from_pretrained(model_name) # 保存到本地 model.save_pretrained("./nanbeige-model") tokenizer.save_pretrained("./nanbeige-model")

方式二：手动下载 访问Hugging Face的Nanbeige页面，下载所有模型文件到本地目录，比如/path/to/your/nanbeige-model/。

3.3 获取项目代码

整个项目的核心就是一个app.py文件。你可以从GitHub获取完整代码，或者按照下面的教程自己创建。

创建一个新的Python文件，命名为app.py，我们将逐步填充内容。

4. 核心代码解析：从零构建聊天界面

4.1 基础框架搭建

我们先从最基础的Streamlit应用结构开始：

import streamlit as st import torch from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer from threading import Thread import time # 页面配置 st.set_page_config( page_title="Nanbeige 4.1-3B Chat", page_icon="🌸", layout="wide", initial_sidebar_state="collapsed" ) # 模型路径配置 MODEL_PATH = "/path/to/your/nanbeige-model" # 修改为你的实际路径 # 初始化session state if "messages" not in st.session_state: st.session_state.messages = [] if "model_loaded" not in st.session_state: st.session_state.model_loaded = False

这段代码做了几件事：

导入必要的库
配置Streamlit页面（标题、图标、布局）
设置模型路径（需要你修改为实际路径）
初始化会话状态，用于保存聊天记录和模型加载状态

4.2 注入自定义CSS样式

这是实现美观界面的关键。我们在Streamlit中注入自定义CSS：

def inject_custom_css(): """注入自定义CSS样式"""" <style> /* 全局样式 */ .stApp { background: linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%); } /* 聊天容器 */ .chat-container { max-width: 800px; margin: 0 auto; padding: 20px; } /* 用户消息气泡 */ .user-message { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; border-radius: 18px 18px 4px 18px; padding: 12px 16px; margin: 8px 0; max-width: 70%; margin-left: auto; box-shadow: 0 2px 5px rgba(0,0,0,0.1); } /* AI消息气泡 */ .ai-message { background: white; color: #333; border-radius: 18px 18px 18px 4px; padding: 12px 16px; margin: 8px 0; max-width: 70%; box-shadow: 0 2px 5px rgba(0,0,0,0.05); border: 1px solid #eaeaea; } /* 思考过程折叠面板 */ .thinking-panel { background: #f8f9fa; border-radius: 8px; padding: 10px; margin: 5px 0; border-left: 4px solid #6c757d; } /* 输入框样式 */ .stTextInput > div > div > input { border-radius: 25px; padding: 12px 20px; border: 2px solid #e0e0e0; } /* 按钮样式 */ .stButton > button { border-radius: 20px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; border: none; } </style> """ st.markdown(custom_css, unsafe_allow_html=True)

这个CSS定义了：

渐变背景色
圆角聊天气泡（用户右对齐，AI左对齐）
思考过程的折叠面板样式
圆角输入框和按钮

4.3 加载模型函数

我们需要一个函数来加载模型，考虑到模型较大，我们使用缓存避免重复加载：

@st.cache_resource def load_model_and_tokenizer(): """加载模型和分词器""" try: st.info("正在加载模型，这可能需要几分钟...") # 加载分词器 tokenizer = AutoTokenizer.from_pretrained( MODEL_PATH, trust_remote_code=True ) # 加载模型 model = AutoModelForCausalLM.from_pretrained( MODEL_PATH, torch_dtype=torch.float16, # 使用半精度减少显存占用 device_map="auto", # 自动分配设备 trust_remote_code=True ) # 设置为评估模式 model.eval() st.success("模型加载成功！") return model, tokenizer except Exception as e: st.error(f"模型加载失败: {str(e)}") return None, None

这里有几个关键点：

@st.cache_resource：Streamlit的缓存装饰器，避免每次交互都重新加载模型
torch_dtype=torch.float16：使用半精度浮点数，减少显存占用
device_map="auto"：自动选择GPU或CPU
trust_remote_code=True：信任远程代码，某些模型需要这个参数

4.4 多模型Chat Template适配

这是本教程的核心部分。不同的模型有不同的对话格式要求，我们需要一个通用的解决方案：

def apply_chat_template(messages, tokenizer, model_name="nanbeige"): """应用聊天模板，支持多种模型格式""" # Nanbeige格式 if model_name.lower() == "nanbeige": for message in messages: role = message["role"] content = message["content"] if role == "user": prompt += f"用户: {content}\n\n助手: " elif role == "assistant": prompt += f"{content}\n\n" return prompt # Qwen格式 elif model_name.lower() == "qwen": for message in messages: role = message["role"] content = message["content"] if role == "user": prompt += f"<|im_start|>user\n{content}<|im_end|>\n<|im_start|>assistant\n" elif role == "assistant": prompt += f"{content}<|im_end|>\n" return prompt # Llama格式 elif model_name.lower() == "llama": for message in messages: role = message["role"] content = message["content"] if role == "user": prompt += f"[INST] {content} [/INST] " elif role == "assistant": prompt += f"{content} " return prompt # 通用格式（如果没有特殊要求） else: # 使用tokenizer自带的apply_chat_template方法 try: prompt = tokenizer.apply_chat_template( messages, tokenize=False, add_generation_prompt=True ) return prompt except: # 如果失败，使用简单格式 for message in messages: prompt += f"{message['role']}: {message['content']}\n" prompt += "assistant: " return prompt

这个函数支持多种模型的对话格式：

Nanbeige：使用"用户:"和"助手:"的简单格式
Qwen：使用特殊的标记格式
Llama：使用[INST]标记
通用格式：尝试使用tokenizer自带的模板

你只需要在调用时指定模型类型，就能自动适配正确的格式。

4.5 流式生成响应

为了实现打字机效果，我们需要流式生成AI的回复：

def generate_response_stream(model, tokenizer, messages, model_type="nanbeige"): """流式生成AI响应""" # 应用聊天模板 prompt = apply_chat_template(messages, tokenizer, model_type) # 编码输入 inputs = tokenizer(prompt, return_tensors="pt").to(model.device) # 创建流式处理器 streamer = TextIteratorStreamer( tokenizer, skip_prompt=True, skip_special_tokens=True ) # 生成参数 generation_kwargs = dict( inputs, streamer=streamer, max_new_tokens=1024, temperature=0.7, top_p=0.9, do_sample=True, repetition_penalty=1.1, ) # 在新线程中生成 thread = Thread(target=model.generate, kwargs=generation_kwargs) thread.start() # 流式输出 in_thinking = False for token in streamer: # 处理思考过程（</think>...</think>格式） if "</think>" in token: in_thinking = True thinking_content += token continue elif "</think>" in token: in_thinking = False # 这里可以保存思考过程到session state if "thinking" not in st.session_state: st.session_state.thinking = [] st.session_state.thinking.append(thinking_content) continue if in_thinking: thinking_content += token else: full_response += token yield token return full_response

这个函数实现了：

将对话历史转换为模型能理解的格式
使用TextIteratorStreamer实现流式输出
特殊处理思考过程（...格式），将其折叠保存
逐步返回生成的文本，实现打字机效果

4.6 主界面布局

现在我们来构建主界面：

def main(): """主函数""" # 注入CSS inject_custom_css() # 标题区域 st.title("🌸 Nanbeige 4.1-3B Chat") st.caption("基于Streamlit的极简聊天界面 | 支持流式输出和多模型适配") # 侧边栏配置 with st.sidebar: st.header("配置") # 模型选择 model_type = st.selectbox( "选择模型类型", ["nanbeige", "qwen", "llama", "custom"], help="选择对应的模型以应用正确的对话格式" ) # 参数调整 temperature = st.slider("温度", 0.1, 1.5, 0.7, 0.1) max_tokens = st.slider("最大生成长度", 128, 2048, 1024, 128) # 清空聊天记录按钮 if st.button("清空聊天记录", type="secondary"): st.session_state.messages = [] if "thinking" in st.session_state: st.session_state.thinking = [] st.rerun() # 主聊天区域 chat_container = st.container() with chat_container: # 显示聊天记录 for i, message in enumerate(st.session_state.messages): role = message["role"] content = message["content"] if role == "user": # 用户消息 with st.chat_message("user"): st.markdown(f'<div>{content}</div>', unsafe_allow_html=True) else: # AI消息 with st.chat_message("assistant"): st.markdown(f'<div>{content}</div>', unsafe_allow_html=True) # 如果有思考过程，显示折叠面板 if "thinking" in st.session_state and i < len(st.session_state.thinking): with st.expander("查看思考过程"): st.markdown(f'<div>{st.session_state.thinking[i]}</div>', unsafe_allow_html=True) # 输入区域 if prompt := st.chat_input("输入你的消息..."): # 添加用户消息 st.session_state.messages.append({"role": "user", "content": prompt}) # 显示用户消息 with chat_container: with st.chat_message("user"): st.markdown(f'<div>{prompt}</div>', unsafe_allow_html=True) # 显示AI回复占位符 with chat_container: with st.chat_message("assistant"): response_placeholder = st.empty() # 确保模型已加载 if not st.session_state.model_loaded: model, tokenizer = load_model_and_tokenizer() if model and tokenizer: st.session_state.model = model st.session_state.tokenizer = tokenizer st.session_state.model_loaded = True else: st.error("模型加载失败，请检查路径和配置") return # 流式生成回复 for chunk in generate_response_stream( st.session_state.model, st.session_state.tokenizer, st.session_state.messages, model_type ): full_response += chunk response_placeholder.markdown( f'<div>{full_response}</div>', unsafe_allow_html=True ) # 保存完整的回复 st.session_state.messages.append({ "role": "assistant", "content": full_response }) if __name__ == "__main__": main()

这个主函数完成了：

页面布局（标题、侧边栏、主聊天区）
聊天记录的显示和管理
用户输入的处理
AI回复的流式显示
思考过程的折叠显示

5. 完整代码整合

将上面的所有代码片段整合到一个app.py文件中，你就得到了完整的应用。记得修改MODEL_PATH为你的实际模型路径。

6. 运行与测试

6.1 启动应用

在终端中运行：

streamlit run app.py

Streamlit会自动打开浏览器，访问http://localhost:8501。

6.2 测试不同功能

基础对话测试：输入"你好"，查看AI的回复
流式输出测试：输入一个较长的问题，观察打字机效果
思考过程测试：如果模型支持CoT，查看折叠的思考过程
多轮对话测试：进行连续对话，查看上下文是否保持

6.3 常见问题解决

问题1：模型加载失败

检查MODEL_PATH路径是否正确
确保有足够的磁盘空间和内存
尝试使用torch_dtype=torch.float32如果半精度有问题

问题2：显存不足

减少max_new_tokens参数
使用CPU模式：device_map="cpu"
启用量化（如果模型支持）

问题3：界面显示异常

检查CSS是否正确注入
确保Streamlit版本是最新的
清除浏览器缓存

7. 适配其他模型

这个框架最大的优势是易于适配其他模型。以Qwen为例，只需要：

7.1 修改模型路径

MODEL_PATH = "/path/to/your/qwen-model"

7.2 调整生成参数

不同模型可能需要不同的生成参数：

# Qwen特定的生成参数 generation_kwargs = dict( inputs, streamer=streamer, max_new_tokens=1024, temperature=0.8, # 稍微高一点的温度 top_p=0.9, do_sample=True, repetition_penalty=1.05, # 不同的重复惩罚 )

7.3 处理特殊格式

如果模型有特殊的停止标记或格式要求，可以在generate_response_stream函数中添加处理逻辑。

8. 进阶优化建议

8.1 性能优化

模型量化：使用bitsandbytes进行4-bit或8-bit量化
缓存优化：实现对话历史的token缓存
批处理：如果有多个用户，考虑批处理请求

8.2 功能扩展

多模型切换：在界面上添加模型切换功能
对话导出：添加导出聊天记录为Markdown或PDF的功能
预设提示词：添加常用提示词模板
API支持：将后端封装为API，支持其他前端调用

8.3 界面美化

主题切换：添加深色/浅色主题切换
动画效果：添加消息发送/接收的动画
响应式设计：优化移动端显示
自定义头像：允许用户上传自定义头像

9. 总结

通过这个教程，我们完成了一个功能完整、界面美观的AI聊天Web应用。这个方案有几个关键优势：

易于部署：单文件部署，依赖简单
界面美观：通过CSS实现了现代聊天应用的设计
多模型支持：通过Chat Template适配器支持多种模型格式
流式输出：实现了流畅的打字机效果
易于扩展：代码结构清晰，方便添加新功能

最重要的是，这个方案展示了如何用纯Python和Streamlit构建复杂的Web应用。你不需要成为前端专家，也能创建出专业的AI应用界面。

现在你可以基于这个框架，创建自己的AI应用了。无论是用于学习、研究还是产品原型，这个方案都能提供一个良好的起点。

获取更多AI镜像

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

Nanbeige 4.1-3B Streamlit WebUI实战教程：适配多模型Chat Template方案

优质文章学习记录