Nanbeige 4.1-3B Streamlit UI从零开始：无React/Vue纯Python驱动前端方案
你是不是也遇到过这样的烦恼？想给本地的大语言模型做个好看的对话界面，结果发现要么得学React、Vue这些前端框架，要么只能用Streamlit那种默认的“程序员审美”界面——侧边栏占一半屏幕，聊天框方方正正，怎么看都像是个内部工具，而不是一个让人想用的产品。
今天我要分享的，就是一个完全不同的思路。不用React，不用Vue，甚至不用写一行JavaScript，只用纯Python和Streamlit，就能打造出一个现代、极简、有设计感的聊天界面。这个方案专门为南北阁（Nanbeige）4.1-3B模型优化，但它的核心思想可以轻松迁移到任何支持流式输出的开源大模型上。
先说说这个界面长什么样。它借鉴了现代手机短信和二次元游戏聊天界面的设计语言：清爽的浅灰蓝背景配上极简的圆点网格，对话气泡左右分明，用户消息在右（天蓝色背景），AI回复在左（纯白背景带柔和阴影）。输入框是悬浮的药丸形状，整个界面没有任何多余的按钮和控件，视觉焦点完全集中在对话本身。
最让我满意的是，这个方案解决了Streamlit原生组件的一个老大难问题——动态布局。传统Streamlit界面里，所有元素都是从上到下线性排列的，想实现类似微信那样的左右气泡对话，几乎不可能。但我们通过一些CSS“魔法”，硬是让Streamlit做到了这一点。
1. 为什么选择纯Streamlit方案？
在开始动手之前，你可能会有疑问：现在前端框架这么多，为什么非要跟Streamlit较劲？直接用React写个界面不是更灵活吗？
这个问题问得好。我选择纯Streamlit方案，主要是基于以下几个考虑：
开发效率的极致追求 用React或Vue开发一个完整的Web应用，你需要处理前后端分离、API接口设计、状态管理、打包部署等一系列问题。即使有现成的模板，学习成本和调试时间也不低。而Streamlit的最大优势就是“所见即所得”——写Python代码的同时就在构建界面，后端逻辑和前端展示天然集成。
部署的简单性 Streamlit应用本质上是一个Python脚本，部署时只需要一个能运行Python的环境。你不需要配置Nginx、不需要处理跨域、不需要构建前端资源。对于个人项目或者内部工具来说，这种简单性非常有吸引力。
Python开发者的友好性 如果你主要是个Python开发者，可能对JavaScript生态并不熟悉。强迫自己为了一个聊天界面去学习一整套前端技术栈，投入产出比可能不高。用纯Python方案，你可以继续在自己熟悉的领域解决问题。
其实Streamlit也能很好看 很多人对Streamlit的印象还停留在它默认的UI组件上——确实不太好看。但很少有人知道，Streamlit支持深度定制CSS，只要你愿意花点时间，完全能做出不输专业前端框架的视觉效果。
当然，这个方案也有它的局限性。如果你的界面需要非常复杂的交互逻辑、实时数据更新或者大量的客户端计算，那么传统的React/Vue方案可能更合适。但对于一个以对话为核心的聊天界面来说，纯Streamlit方案已经足够强大。
2. 环境准备与快速启动
2.1 安装依赖
这个项目需要的依赖非常少，主要是Streamlit和模型推理相关的库。建议使用Python 3.10或更高版本。
打开终端，执行以下命令：
pip install streamlit torch transformers accelerate
这里简单解释一下每个包的作用：
- streamlit：我们的Web框架，负责构建界面和处理用户交互
- torch：PyTorch深度学习框架，模型推理的基础
- transformers：Hugging Face的Transformer库，加载和使用大模型的核心
- accelerate：优化模型加载和推理，特别是在内存有限的情况下
2.2 准备模型权重
你需要先下载南北阁4.1-3B的模型权重。可以从Hugging Face模型库获取：
# 使用git-lfs下载（推荐）
git lfs install
git clone https://huggingface.co/Nanbeige/Nanbeige4___1-3B
# 或者直接下载
# 访问 https://huggingface.co/Nanbeige/Nanbeige4___1-3B 手动下载
下载完成后，记住模型权重存放的本地路径。比如我放在 /home/user/models/nanbeige-4.1-3B/。
2.3 核心代码结构
整个应用只有一个文件：app.py。下面是这个文件的基本结构：
# app.py – 完整应用代码
import streamlit as st
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM, 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"
)
# 自定义CSS样式
def load_css():
# 这里会注入我们的CSS魔法
pass
# 加载模型和分词器
@st.cache_resource
def load_model():
# 加载模型，使用缓存避免重复加载
pass
# 流式生成函数
def generate_stream(prompt, history):
# 处理对话历史，生成回复
pass
# 主界面
def main():
# 初始化会话状态
if "messages" not in st.session_state:
st.session_state.messages = []
# 加载CSS
load_css()
# 页面标题和清空按钮
st.markdown("<div class='header'>", unsafe_allow_html=True)
col1, col2 = st.columns([6, 1])
with col1:
st.title("🌸 Nanbeige 4.1-3B Chat")
with col2:
if st.button("清空记录", use_container_width=True):
st.session_state.messages = []
st.rerun()
st.markdown("</div>", unsafe_allow_html=True)
# 聊天历史显示区域
chat_container = st.container()
# 输入区域
with st.form("chat_form", clear_on_submit=True):
user_input = st.text_area(
"输入消息",
placeholder="输入你想说的话…",
label_visibility="collapsed",
height=100
)
submitted = st.form_submit_button("发送")
# 处理用户输入
if submitted and user_input:
# 添加用户消息到历史
st.session_state.messages.append({"role": "user", "content": user_input})
# 生成AI回复
with st.spinner("思考中…"):
response = generate_stream(user_input, st.session_state.messages)
st.session_state.messages.append({"role": "assistant", "content": response})
# 重新运行以更新界面
st.rerun()
if __name__ == "__main__":
main()
这是一个简化版的框架，展示了应用的基本流程。接下来我们会逐步填充每个函数的具体实现。
3. 核心功能实现详解
3.1 CSS魔法：让Streamlit变身现代聊天界面
这是整个项目最核心的部分。Streamlit默认的样式很基础，但我们可以通过注入自定义CSS来彻底改变它的外观。
在 load_css() 函数中，我们添加以下样式：
def load_css():
st.markdown("""
<style>
/* 全局样式重置 */
.stApp {
max-width: 800px;
margin: 0 auto;
padding: 20px;
background: linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%);
}
/* 隐藏Streamlit默认元素 */
#MainMenu {visibility: hidden;}
footer {visibility: hidden;}
header {visibility: hidden;}
/* 聊天容器 */
.chat-container {
display: flex;
flex-direction: column;
gap: 16px;
margin-bottom: 100px;
}
/* 消息气泡基础样式 */
.message {
max-width: 70%;
padding: 12px 16px;
border-radius: 18px;
position: relative;
word-wrap: break-word;
line-height: 1.5;
}
/* 用户消息（右侧） */
.user-message {
align-self: flex-end;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
border-bottom-right-radius: 4px;
}
/* AI消息（左侧） */
.ai-message {
align-self: flex-start;
background: white;
color: #333;
box-shadow: 0 2px 12px rgba(0, 0, 0, 0.1);
border-bottom-left-radius: 4px;
}
/* 消息头像 */
.avatar {
width: 36px;
height: 36px;
border-radius: 50%;
display: flex;
align-items: center;
justify-content: center;
font-weight: bold;
margin: 0 8px;
}
.user-avatar {
background: #667eea;
color: white;
order: 2;
}
.ai-avatar {
background: #f0f0f0;
color: #666;
order: 1;
}
/* 消息行容器 – 关键技巧在这里！ */
.message-row {
display: flex;
align-items: flex-end;
margin-bottom: 8px;
}
/* 使用:has()选择器判断消息方向 */
.message-row:has(.user-message) {
flex-direction: row-reverse;
}
.message-row:has(.ai-message) {
flex-direction: row;
}
/* 输入区域样式 */
.stTextArea textarea {
border-radius: 24px;
border: 2px solid #e0e0e0;
padding: 16px;
font-size: 16px;
transition: all 0.3s ease;
}
.stTextArea textarea:focus {
border-color: #667eea;
box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
outline: none;
}
/* 按钮样式 */
.stButton button {
border-radius: 24px;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
border: none;
font-weight: 600;
transition: all 0.3s ease;
}
.stButton button:hover {
transform: translateY(-2px);
box-shadow: 0 6px 20px rgba(102, 126, 234, 0.3);
}
/* 流式输出时的打字机效果 */
@keyframes blink {
0%, 100% { opacity: 1; }
50% { opacity: 0; }
}
.typing-cursor::after {
content: "|";
animation: blink 1s infinite;
color: #667eea;
font-weight: bold;
}
</style>
""", unsafe_allow_html=True)
这段CSS代码做了几件重要的事情：
:has() 选择器是这个方案的核心。它允许我们根据子元素的状态来设置父元素的样式。当 .message-row 包含 .user-message 时，我们设置 flex-direction: row-reverse，这样用户头像和消息就会左右互换，实现右侧对齐的效果。
3.2 模型加载与流式输出
接下来是模型加载部分。我们使用 @st.cache_resource 装饰器来缓存模型，避免每次交互都重新加载。
@st.cache_resource
def load_model():
# 修改为你自己的模型路径
MODEL_PATH = "/home/user/models/nanbeige-4.1-3B"
print("正在加载模型和分词器…")
# 加载分词器
tokenizer = AutoTokenizer.from_pretrained(
MODEL_PATH,
trust_remote_code=True
)
# 加载模型
model = AutoModelForCausalLM.from_pretrained(
MODEL_PATH,
torch_dtype=torch.float16, # 使用半精度减少内存占用
device_map="auto", # 自动分配设备（CPU/GPU）
trust_remote_code=True
)
# 设置为评估模式
model.eval()
print("模型加载完成！")
return model, tokenizer
流式输出是聊天应用的关键体验。我们使用 TextIteratorStreamer 来实现打字机效果：
def generate_stream(prompt, history):
model, tokenizer = load_model()
# 构建对话历史
messages = []
for msg in history[-6:]: # 只保留最近6轮对话，避免上下文过长
messages.append({"role": msg["role"], "content": msg["content"]})
messages.append({"role": "user", "content": prompt})
# 应用聊天模板
text = tokenizer.apply_chat_template(
messages,
tokenize=False,
add_generation_prompt=True
)
# 编码输入
inputs = tokenizer(text, 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()
# 收集流式输出
generated_text = ""
for token in streamer:
generated_text += token
# 这里可以添加实时显示逻辑
# 但为了简化，我们先收集完整文本再返回
thread.join()
# 处理思考过程（CoT）
if "</think>" in generated_text and "<think>" in generated_text:
# 提取思考过程
start = generated_text.find("<think>")
end = generated_text.find("</think>") + 2
if start != -1 and end != -1:
cot_content = generated_text[start:end]
main_content = generated_text[end:].strip()
# 格式化输出：思考过程折叠，主要内容正常显示
formatted = f"**思考过程**（点击展开）\\n\\n{cot_content}\\n\\n**回答**\\n\\n{main_content}"
return formatted
return generated_text
这段代码有几个关键点：
3.3 界面渲染与消息显示
现在我们需要修改主函数，用我们自定义的样式来显示消息：
def main():
# 初始化会话状态
if "messages" not in st.session_state:
st.session_state.messages = []
# 加载CSS
load_css()
# 页面标题和清空按钮
st.markdown("<div class='header'>", unsafe_allow_html=True)
col1, col2 = st.columns([6, 1])
with col1:
st.title("🌸 Nanbeige 4.1-3B Chat")
with col2:
if st.button("清空记录", use_container_width=True):
st.session_state.messages = []
st.rerun()
st.markdown("</div>", unsafe_allow_html=True)
# 聊天历史显示
chat_container = st.container()
with chat_container:
st.markdown("<div class='chat-container'>", unsafe_allow_html=True)
for i, message in enumerate(st.session_state.messages):
role = message["role"]
content = message["content"]
# 判断消息类型
if role == "user":
avatar = "👤"
message_class = "user-message"
avatar_class = "user-avatar"
else:
avatar = "🤖"
message_class = "ai-message"
avatar_class = "ai-avatar"
# 渲染消息行
st.markdown(f"""
<div class='message-row'>
<div class='avatar {avatar_class}'>{avatar}</div>
<div class='message {message_class}'>
{content}
</div>
</div>
""", unsafe_allow_html=True)
st.markdown("</div>", unsafe_allow_html=True)
# 输入区域
with st.form("chat_form", clear_on_submit=True):
user_input = st.text_area(
"输入消息",
placeholder="输入你想说的话…",
label_visibility="collapsed",
height=100,
key=f"input_{len(st.session_state.messages)}"
)
col1, col2, col3 = st.columns([1, 1, 1])
with col2:
submitted = st.form_submit_button(
"发送",
use_container_width=True,
type="primary"
)
# 处理用户输入
if submitted and user_input:
# 添加用户消息
st.session_state.messages.append({
"role": "user",
"content": user_input
})
# 显示用户消息后立即更新界面
st.rerun()
# 生成AI回复
with st.spinner("思考中…"):
try:
response = generate_stream(
user_input,
st.session_state.messages[:-1] # 不包含刚添加的用户消息
)
# 添加AI回复
st.session_state.messages.append({
"role": "assistant",
"content": response
})
except Exception as e:
st.error(f"生成失败: {str(e)}")
st.session_state.messages.append({
"role": "assistant",
"content": f"抱歉，生成回复时出现错误: {str(e)}"
})
# 再次更新界面显示AI回复
st.rerun()
这里有几个重要的细节：
3.4 高级功能：思考过程折叠
南北阁4.1-3B支持思维链（Chain-of-Thought）推理，会在输出中包含 <think>…</think> 格式的思考过程。我们可以让这些内容默认折叠，保持界面清爽。
修改消息渲染部分，添加折叠支持：
# 在渲染AI消息时
if role == "assistant":
# 检查是否包含思考过程
if "**思考过程**" in content and "**回答**" in content:
# 分割内容
parts = content.split("**回答**")
thought = parts[0].replace("**思考过程**（点击展开）", "").strip()
answer = parts[1].strip()
# 使用Streamlit的expander组件
with st.expander("🤔 查看思考过程", expanded=False):
st.markdown(thought)
st.markdown(f"""
<div class='message-row'>
<div class='avatar ai-avatar'>🤖</div>
<div class='message ai-message'>
{answer}
</div>
</div>
""", unsafe_allow_html=True)
else:
# 正常显示
st.markdown(f"""
<div class='message-row'>
<div class='avatar ai-avatar'>🤖</div>
<div class='message ai-message'>
{content}
</div>
</div>
""", unsafe_allow_html=True)
这样，当AI的回复中包含思考过程时，思考部分会被折叠起来，用户点击才能展开。主界面只显示最终的回答，保持简洁。
4. 完整代码与使用技巧
4.1 完整app.py代码
把上面的所有代码片段组合起来，就是完整的 app.py：
import streamlit as st
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM, TextIteratorStreamer
from threading import Thread
# 页面配置
st.set_page_config(
page_title="Nanbeige 4.1-3B Chat",
page_icon="🌸",
layout="wide",
initial_sidebar_state="collapsed"
)
# 自定义CSS
def load_css():
st.markdown("""
<style>
/* 这里放入前面提到的完整CSS代码 */
</style>
""", unsafe_allow_html=True)
# 加载模型
@st.cache_resource
def load_model():
MODEL_PATH = "/home/user/models/nanbeige-4.1-3B" # 修改为你的路径
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()
return model, tokenizer
# 流式生成
def generate_stream(prompt, history):
model, tokenizer = load_model()
messages = []
for msg in history[-6:]:
messages.append({"role": msg["role"], "content": msg["content"]})
messages.append({"role": "user", "content": prompt})
text = tokenizer.apply_chat_template(
messages,
tokenize=False,
add_generation_prompt=True
)
inputs = tokenizer(text, 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()
generated_text = ""
for token in streamer:
generated_text += token
thread.join()
# 处理思考过程
if "</think>" in generated_text and "<think>" in generated_text:
start = generated_text.find("<think>")
end = generated_text.find("</think>") + 2
if start != -1 and end != -1:
cot_content = generated_text[start:end]
main_content = generated_text[end:].strip()
return f"**思考过程**（点击展开）\\n\\n{cot_content}\\n\\n**回答**\\n\\n{main_content}"
return generated_text
# 主函数
def main():
if "messages" not in st.session_state:
st.session_state.messages = []
load_css()
# 标题和清空按钮
st.markdown("<div class='header'>", unsafe_allow_html=True)
col1, col2 = st.columns([6, 1])
with col1:
st.title("🌸 Nanbeige 4.1-3B Chat")
with col2:
if st.button("清空记录", use_container_width=True):
st.session_state.messages = []
st.rerun()
st.markdown("</div>", unsafe_allow_html=True)
# 聊天历史
chat_container = st.container()
with chat_container:
st.markdown("<div class='chat-container'>", unsafe_allow_html=True)
for i, message in enumerate(st.session_state.messages):
role = message["role"]
content = message["content"]
if role == "user":
st.markdown(f"""
<div class='message-row'>
<div class='avatar user-avatar'>👤</div>
<div class='message user-message'>
{content}
</div>
</div>
""", unsafe_allow_html=True)
else:
if "**思考过程**" in content and "**回答**" in content:
parts = content.split("**回答**")
thought = parts[0].replace("**思考过程**（点击展开）", "").strip()
answer = parts[1].strip()
with st.expander("🤔 查看思考过程", expanded=False):
st.markdown(thought)
st.markdown(f"""
<div class='message-row'>
<div class='avatar ai-avatar'>🤖</div>
<div class='message ai-message'>
{answer}
</div>
</div>
""", unsafe_allow_html=True)
else:
st.markdown(f"""
<div class='message-row'>
<div class='avatar ai-avatar'>🤖</div>
<div class='message ai-message'>
{content}
</div>
</div>
""", unsafe_allow_html=True)
st.markdown("</div>", unsafe_allow_html=True)
# 输入区域
with st.form("chat_form", clear_on_submit=True):
user_input = st.text_area(
"输入消息",
placeholder="输入你想说的话…",
label_visibility="collapsed",
height=100,
key=f"input_{len(st.session_state.messages)}"
)
col1, col2, col3 = st.columns([1, 1, 1])
with col2:
submitted = st.form_submit_button(
"发送",
use_container_width=True,
type="primary"
)
# 处理输入
if submitted and user_input:
st.session_state.messages.append({
"role": "user",
"content": user_input
})
st.rerun()
with st.spinner("思考中…"):
try:
response = generate_stream(
user_input,
st.session_state.messages[:-1]
)
st.session_state.messages.append({
"role": "assistant",
"content": response
})
except Exception as e:
st.error(f"生成失败: {str(e)}")
st.session_state.messages.append({
"role": "assistant",
"content": f"抱歉，生成回复时出现错误: {str(e)}"
})
st.rerun()
if __name__ == "__main__":
main()
4.2 使用技巧与优化建议
性能优化 如果你的显卡内存有限，可以尝试以下优化：
# 使用4位量化（需要bitsandbytes）
model = AutoModelForCausalLM.from_pretrained(
MODEL_PATH,
load_in_4bit=True, # 4位量化
bnb_4bit_compute_dtype=torch.float16,
device_map="auto",
trust_remote_code=True
)
# 或者使用8位量化
model = AutoModelForCausalLM.from_pretrained(
MODEL_PATH,
load_in_8bit=True, # 8位量化
device_map="auto",
trust_remote_code=True
)
样式自定义 想要改变界面风格？只需要修改CSS中的颜色值：
/* 修改主题色 */
.user-message {
background: linear-gradient(135deg, #FF6B6B 0%, #FF8E53 100%); /* 橙色系 */
}
.ai-message {
background: linear-gradient(135deg, #4ECDC4 0%, #44A08D 100%); /* 青色系 */
}
/* 修改背景 */
.stApp {
background: linear-gradient(135deg, #ECE9E6 0%, #FFFFFF 100%); /* 浅灰渐变 */
}
添加更多功能 你可以根据需要扩展功能：
5. 总结
通过这个项目，我们证明了即使只用纯Python和Streamlit，也能打造出美观、实用的现代Web应用。这个方案有几个明显的优势：
开发效率高 从零开始到完整可用的聊天界面，只需要一个Python文件，几百行代码。不需要学习前端框架，不需要处理复杂的构建配置。
部署简单 只需要Python环境就能运行，部署到服务器就是一条命令的事情。对于个人项目或者内部工具来说，这种简单性非常有价值。
定制灵活 CSS提供了几乎无限的定制可能性。你可以轻松调整颜色、布局、动画效果，打造完全符合你品牌风格的界面。
性能足够 对于聊天这种交互模式，Streamlit的性能完全足够。虽然每次交互都会重新运行整个脚本，但通过合理的状态管理和缓存，用户体验依然流畅。
可扩展性强 这个架构很容易扩展。你可以添加更多的AI功能，集成不同的模型，或者增加业务逻辑。所有的代码都在一个地方，维护起来也很方便。
当然，这个方案最适合的是中小型项目、原型验证、或者个人工具。如果你需要构建一个高并发、实时性要求极高的生产级应用，可能还是需要考虑更专业的前后端分离架构。
但无论如何，对于大多数想要快速给大模型做个好看界面的开发者来说，这个纯Python方案绝对值得一试。它打破了"Streamlit只能做简陋界面"的刻板印象，展示了Python生态在Web开发中的另一种可能性。
最后，这个项目的所有代码都是开源的，你可以自由修改、扩展，或者把它适配到其他大模型上。希望这个方案能给你带来启发，也欢迎分享你的改进和创意。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
