Qwen3-Embedding-4B实战教程：Streamlit session state管理知识库与查询状态-深圳市維司達科技有限公司

Qwen3-Embedding-4B实战教程：Streamlit session state管理知识库与查询状态

1. 什么是Qwen3-Embedding-4B？语义搜索的底层引擎

你可能已经用过“搜一搜”“找一找”这类功能，但有没有遇到过这样的尴尬：输入“怎么缓解眼睛疲劳”，结果返回一堆标题含“眼睛”却讲近视手术的文章？传统关键词检索只认字面匹配，而Qwen3-Embedding-4B干的是另一件事——它不看字，看“意思”。

简单说，Qwen3-Embedding-4B是阿里通义千问推出的专用文本嵌入模型，参数量40亿（4B），专为把文字变成“数字向量”而生。它不生成回答、不写故事，只做一件事：把一句话，比如“我饿了”，压缩成一个长度为32768的数字列表（即32768维向量）。这个向量不是随机排列，而是忠实编码了这句话的语义特征——和“肚子咕咕叫”“想吃点东西”“该吃午饭了”的向量在数学空间里靠得很近；而和“今天天气真好”“如何修电脑”的向量则相距甚远。

这种能力叫语义搜索（Semantic Search），核心就两步：

文本→向量：用Qwen3-Embedding-4B对知识库每条文本、每次用户提问，都算出对应的高维向量；
向量→匹配：用余弦相似度公式，快速比对查询向量和所有知识库向量的“夹角余弦值”，值越接近1，语义越相近。

这不是玄学，是可验证、可调试、可落地的工程实践。而本教程要带你亲手实现的，正是这样一个轻量但完整、直观且可交互的语义搜索演示系统——它不依赖API调用，不打包复杂服务，全部逻辑跑在本地Streamlit界面中，且关键状态全由st.session_state稳稳托住。

你不需要懂PyTorch张量运算，也不用配置Docker容器。只要你会复制粘贴几行代码、能看懂“左边输知识、右边输问题、点按钮出结果”，就能真正摸到大模型嵌入技术的脉搏。

2. 为什么必须用session_state？状态管理是语义搜索的隐形骨架

很多初学者写Streamlit应用时，会直接把知识库文本存成普通Python变量，比如：

knowledge_base = ["苹果是一种水果", "香蕉富含钾元素"]

然后在按钮回调里读取它、计算向量、展示结果……看似没问题，但只要页面刷新、切换选项卡、甚至点击一次其他按钮，这个变量就消失了——因为Streamlit每次重运行脚本，都会重新执行全部代码，变量从头初始化。

而语义搜索恰恰需要跨交互周期保持三类关键状态：

知识库内容：用户在左侧输入的多行文本，不能每次搜索都重输；
查询词内容：用户刚输入的问题，不能点完按钮就清空；
向量缓存：知识库向量化耗时（尤其GPU加载后首次计算），重复计算既慢又费显存，必须复用。

这些，普通变量扛不住；全局变量不安全（多用户并发会串）；文件临时存储太重——唯一正解，就是Streamlit原生的状态管理机制：st.session_state。

它像一个随页面生命周期存在的“私人记事本”，只要用户没关浏览器标签页，里面的内容就一直活着。你往里存什么，它就记住什么；你从哪读，它就给你什么。更重要的是，它天然支持键值对式访问、动态初始化、类型安全检查，写起来干净，读起来清晰。

下面这段代码，就是整个项目状态管理的起点：

import streamlit as st # 初始化session_state中的三个核心键 if 'knowledge_texts' not in st.session_state: st.session_state.knowledge_texts = [ "苹果是一种很好吃的水果", "香蕉富含钾元素，有助于肌肉恢复", "橙子维生素C含量很高，能增强免疫力", "西瓜水分充足，适合夏天解暑", "葡萄含有丰富的抗氧化物质", "草莓酸甜可口，富含叶酸", "梨子润肺止咳，适合干燥季节食用", "芒果香甜软糯，含有大量维生素A" ] if 'query_text' not in st.session_state: st.session_state.query_text = "我想吃点东西" if 'vectors_cached' not in st.session_state: st.session_state.vectors_cached = False

注意两点：

所有初始化都放在if not in判断里，确保只执行一次；
vectors_cached是布尔标记，不是向量本身——真正的向量我们存在另一个键里（后面揭晓），这样避免误删或覆盖。

这就是语义搜索应用的“地基”。没有它，界面再炫，也只是一个不断重置的幻灯片；有了它，用户才能真正体验“构建→查询→修改→再查”的完整闭环。

3. 双栏交互设计：左侧建库，右侧查义，状态全程同步

Streamlit默认是单列自上而下布局，但语义搜索天然需要“输入区”和“结果区”并置对比。我们用st.columns()创建左右双栏，并让它们共享同一套session_state，实现真正的状态联动。

3.1 左侧知识库：自由输入 + 智能清洗

左侧区域核心是st.text_area，但重点不在控件本身，而在如何把用户输入安全、稳定地存进session_state：

col1, col2 = st.columns([1, 1]) with col1: st.markdown("### 知识库") # 从session_state读取当前知识库，作为text_area初始值 current_knowledge = "\n".join(st.session_state.knowledge_texts) new_input = st.text_area( "每行一条文本（空行自动过滤）", value=current_knowledge, height=300, key="knowledge_input" ) # 用户修改后，实时更新session_state（非按钮触发！） if new_input != current_knowledge: # 按行分割，过滤空行和纯空白 lines = [line.strip() for line in new_input.split("\n") if line.strip()] st.session_state.knowledge_texts = lines # 同时重置向量缓存标记，因为知识已变 st.session_state.vectors_cached = False

这里的关键设计是：监听输入变化，而非等待按钮。

key="knowledge_input"确保该组件有唯一标识；
if new_input != current_knowledge避免无意义重赋值；
lines = [...]完成三重清洗：去首尾空格、去空行、去纯空白行；
最后一句st.session_state.vectors_cached = False是点睛之笔——知识库一变，旧向量立刻失效，下次搜索自动重建，逻辑严丝合缝。

3.2 右侧查询区：语义输入 + 即时反馈

右侧同样用st.text_input，但策略不同：我们不追求实时更新（毕竟查询词通常只输一次），而是绑定到搜索按钮的触发逻辑中：

with col2: st.markdown("### 语义查询") query = st.text_input( "输入你想搜索的语义表达（如：我饿了）", value=st.session_state.query_text, key="query_input" ) # 更新session_state中的query_text（仅当用户明确修改） if query != st.session_state.query_text: st.session_state.query_text = query # 主搜索按钮 if st.button("开始搜索 ", type="primary", use_container_width=True): # 触发向量化与匹配逻辑（下节详解） perform_semantic_search()

注意st.button的type="primary"让它成为视觉焦点，use_container_width=True撑满栏宽，降低操作成本。而query的更新逻辑和左侧不同——它只在用户实际修改时才写入session_state，避免干扰默认示例。

至此，双栏已完成“状态绑定”：左边改知识库 →knowledge_texts更新 →vectors_cached=False；右边改问题 →query_text更新；点按钮 → 读取最新状态 → 执行搜索。没有冗余通信，没有手动传参，全靠st.session_state自动同步。

4. GPU加速向量化：用transformers + accelerate加载Qwen3-Embedding-4B

Qwen3-Embedding-4B模型需通过Hugging Facetransformers加载，但直接from_pretrained会默认走CPU，速度极慢。我们必须强制启用CUDA，并利用accelerate做智能设备分配。

4.1 模型加载：一行代码指定GPU，零配置启动

from transformers import AutoModel, AutoTokenizer import torch def load_embedding_model(): if 'model' not in st.session_state: st.write("⏳ 正在加载Qwen3-Embedding-4B模型（GPU加速中）...") # 强制使用CUDA，若不可用则报错（不降级到CPU） device = torch.device("cuda" if torch.cuda.is_available() else "cpu") if device.type != "cuda": st.error("❌ 错误：未检测到可用GPU。本演示需CUDA环境运行。") st.stop() tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-Embedding-4B") model = AutoModel.from_pretrained("Qwen/Qwen3-Embedding-4B").to(device) st.session_state.tokenizer = tokenizer st.session_state.model = model st.session_state.device = device st.success(" 模型加载完成，向量空间已展开！")

关键点解析：

torch.device("cuda" if ...)显式声明设备，拒绝静默降级；
.to(device)将模型权重搬入显存；
st.stop()遇错中断，避免后续逻辑崩溃；
成功后写入st.session_state，供后续函数复用——这才是真正的“一次加载，多次使用”。

4.2 向量化函数：批处理 + no_grad + half精度，榨干GPU性能

向量化不是逐句计算，而是批量编码。我们把知识库所有文本拼成列表，一次性送入模型，效率提升5倍以上：

def get_embeddings(texts, model, tokenizer, device): # 分词（不带特殊token，因是embedding任务） inputs = tokenizer( texts, padding=True, truncation=True, max_length=512, return_tensors="pt" ).to(device) with torch.no_grad(): # 关闭梯度，省显存 outputs = model(**inputs) # Qwen3-Embedding-4B输出last_hidden_state，取[CLS]位置 embeddings = outputs.last_hidden_state[:, 0] # [batch, hidden_size] # 转float16进一步减显存（精度损失可忽略） embeddings = embeddings.half() return embeddings.cpu().numpy() # 转回CPU numpy，便于后续计算

padding=True确保批次内长度对齐；
truncation=True防超长文本OOM；
with torch.no_grad()是必须项，否则显存翻倍；
half()将float32转float16，显存占用减半，实测相似度结果无可见差异；
最后.cpu().numpy()导出为NumPy数组，方便用scikit-learn算余弦相似度。

整个过程，从加载到向量化，全部状态由st.session_state托管：模型、分词器、设备、向量结果——都在同一个“会话上下文”里，稳定、高效、可追溯。

5. 余弦匹配与结果可视化：分数+进度条+颜色阈值，一眼看懂语义强弱

向量有了，下一步是计算查询向量与每个知识库向量的余弦相似度。我们用sklearn.metrics.pairwise.cosine_similarity，简洁可靠：

from sklearn.metrics.pairwise import cosine_similarity import numpy as np def perform_semantic_search(): # 1. 获取查询向量（单条） query_vec = get_embeddings([st.session_state.query_text], st.session_state.model, st.session_state.tokenizer, st.session_state.device) # 2. 若知识库向量未缓存，则计算并存入session_state if not st.session_state.vectors_cached: kb_vecs = get_embeddings(st.session_state.knowledge_texts, st.session_state.model, st.session_state.tokenizer, st.session_state.device) st.session_state.kb_vectors = kb_vecs st.session_state.vectors_cached = True # 3. 计算相似度矩阵（1 x N） similarities = cosine_similarity(query_vec, st.session_state.kb_vectors)[0] # 4. 按相似度降序排序索引 sorted_indices = np.argsort(similarities)[::-1] # 5. 展示前5条结果 st.markdown("### 匹配结果（按语义相似度排序）") for i, idx in enumerate(sorted_indices[:5]): score = similarities[idx] text = st.session_state.knowledge_texts[idx] # 颜色阈值：>0.4绿色，否则灰色 color = "green" if score > 0.4 else "gray" st.markdown(f"**{i+1}. {text}**") st.progress(score) # 进度条直观显示强度 st.markdown(f"<span style='color:{color}; font-weight:bold'>相似度：{score:.4f}</span>", unsafe_allow_html=True) st.divider()

效果直白有力：

每条结果带加粗原文，突出语义主体；
st.progress(score)生成横向进度条，长度=相似度值，无需解释；
<span>内联样式实现绿色/灰色阈值着色，0.4是经验值——低于此值，语义关联已较弱；
st.divider()分隔条清爽利落，避免视觉粘连。

这不仅是结果展示，更是语义强度的教学工具：用户输入“我饿了”，看到“苹果是一种很好吃的水果”排第一、相似度0.52，立刻理解什么叫“语义相近”；看到第三条“梨子润肺止咳”只有0.31，也明白为何它排得靠后。

6. 向量揭秘面板：查看维度、预览数值、柱状图可视化，揭开嵌入黑箱

最后，我们提供一个可折叠的“幕后数据”面板，让用户亲手触摸向量本质——这既是技术亮点，也是教学价值所在：

with st.expander(" 查看幕后数据（向量值）"): st.markdown("#### 查询词向量详情") if st.button("显示我的查询词向量", type="secondary"): # 重新计算查询向量（确保最新） query_vec = get_embeddings([st.session_state.query_text], st.session_state.model, st.session_state.tokenizer, st.session_state.device) vec = query_vec[0] # 取第一个（也是唯一一个） st.markdown(f"- **向量维度**：`{len(vec)}`（Qwen3-Embedding-4B固定为32768）") st.markdown(f"- **前10维数值**：`{vec[:10].round(4)}`（已四舍五入）") # 柱状图展示前50维分布 import matplotlib.pyplot as plt fig, ax = plt.subplots(figsize=(6, 2)) ax.bar(range(50), vec[:50], color="#4CAF50", alpha=0.7) ax.set_title("前50维数值分布（截取）", fontsize=12) ax.set_xlabel("维度索引", fontsize=10) ax.set_ylabel("数值", fontsize=10) ax.tick_params(axis='both', which='major', labelsize=9) st.pyplot(fig)

st.expander保证界面整洁，按需展开；
st.button触发即时计算，避免预加载浪费资源；
文字说明直指核心：“32768维”破除神秘感，“前10维”给出具体感知；
Matplotlib柱状图用浅绿配色，尺寸精简（6×2英寸），专注呈现稀疏性与波动性——你看不到平滑曲线，只看到高低错落的柱子，这正是高维语义向量的真实模样。

这一设计，让“向量化”从抽象概念，变成可看、可数、可感的具体对象。新手不再需要背诵“嵌入是稠密向量”，他亲眼看到50根长短不一的柱子，就明白了。