Streamlit

Streamlit 快速入门

把 Python 脚本变成 Web 应用 —— 无需 HTML/CSS/JS，纯 Python 构建 AI 演示界面。

这是什么？适合谁？

Streamlit 是让数据科学家和 ML 工程师用纯 Python 构建 Web 应用的开源框架。你不需要学前端，只需要写 Python 脚本，Streamlit 自动把它变成交互式网页。GitHub 45K+ stars，Snowflake 旗下（于 2022 年收购），被 Fortune 50 中 90% 的企业使用。

适合谁？一是数据科学家，想快速展示分析结果和模型效果；二是 ML 工程师，需要构建模型演示和内部工具；三是 AI 创业者，想快速搭建产品原型。不适合：需要复杂前端交互的生产级应用（用 React/Next.js），以及需要精细 UI 控制的场景。

准备工作

• 安装：pip install streamlit
• Python：3.8+

3 步快速上手

第 1 步：安装

pip install streamlit

第 2 步：创建 app.py

import streamlit as st
st.title("我的第一个 AI 应用")
user_input = st.text_input("请输入你的问题")
if user_input:
    st.write(f"AI 回复：关于'{user_input}'的分析...")

第 3 步：运行

streamlit run app.py

浏览器自动打开 http://localhost:8501。

常见踩坑

踩坑 1：页面刷新后状态丢失

• 症状：用户输入在刷新后消失
• 原因：Streamlit 默认无状态，每次交互都是重新运行脚本
• 解决：使用 st.session_state 保存状态

踩坑 2：大文件上传慢

• 症状：上传大文件时页面卡住
• 原因：默认 st.file_uploader 在内存中处理
• 解决：使用 st.cache_data 缓存处理结果

踩坑 3：页面加载极慢（超过 10 秒）

• 症状：首页加载时间超过 10 秒
• 原因：脚本顶部的 import 或数据加载没做缓存
• 解决：使用 @st.cache_data 装饰数据加载函数，@st.cache_resource 装饰模型加载等资源初始化

踩坑 4：图表不显示或显示异常

• 症状：st.line_chart() 等图表函数无输出
• 原因：数据格式不符合要求，需要 Pandas DataFrame 格式
• 解决：确保数据是 pd.DataFrame 且列名为字符串类型

踩坑 5：Secret 配置丢失

• 症状：部署后 API Key 不可用
• 原因：本地的 .streamlit/secrets.toml 没有在部署平台配置
• 解决：在 Streamlit Community Cloud 的 Settings → Secrets 中配置相同内容

踩坑 6：多页面应用路由混乱

• 症状：页面 URL 访问 404
• 原因：多页面文件路径不规范
• 解决：确保子页面在 pages/ 目录下，文件名即路由名，如 pages/about.py 对应 /about

踩坑 7：Docker 部署端口映射问题

• 症状：Docker 容器运行后无法访问
• 原因：Streamlit 默认绑定 8501，需要映射到宿主机端口
• 解决：docker run -p 8501:8501 my-streamlit-app，并在 Dockerfile 中设置 SERVER_PORT=8501 环境变量

踩坑 8：st.cache_data 不生效

• 症状：函数仍然每次都重新执行
• 原因：参数包含不可哈希类型（如列表、字典）
• 解决：将不可哈希参数转为元组或字符串，或设置 hash_funcs 参数自定义哈希

FAQ 常见问题

Q1：Streamlit 免费吗？

A：Streamlit 本身是 Apache 2.0 开源项目，完全免费。Streamlit Community Cloud（托管服务）也是免费的——仅限公开应用，需绑定 GitHub 账号。企业级部署需要 Snowflake 账号（付费），起价约 $2000/年起。2024 年被 Fortune 50 中 90% 以上企业采用。来源

Q2：Streamlit 和 Gradio、Dash 有什么区别？

A：Streamlit（45K stars）以”最短代码”著称——50 行 Python 即可完成一个交互式数据应用。Gradio（40K stars）更侧重 ML 模型演示，内置大量 ML 组件（图像分类、NLP 等）。Dash（22K stars）基于 Flask+React，适合复杂仪表盘，但需要 JavaScript 知识。Streamlit 适合快速原型和演示，Gradio 适合模型展示，Dash 适合企业级 BI。来源

Q3：Streamlit 支持多页面应用吗？

A：支持。在 app.py 同级目录创建 pages/ 文件夹，放入 page1.py、page2.py，侧边栏自动生成导航。也可以使用 st.navigation API 自定义导航结构，支持嵌套分组。来源

Q4：Streamlit 怎么和 LangChain/LlamaIndex 集成？

A：直接在 Streamlit 脚本中导入 LangChain 或 LlamaIndex，使用 st.session_state 保存聊天历史，st.chat_message 展示对话气泡。社区有大量模板：https://github.com/streamlit/llm-examples 。需要注意每次交互脚本重跑，必须用 st.session_state 持久化 LLM 会话状态。

Q5：Streamlit 能处理高并发吗？

A：Streamlit 单实例是单线程的，不适合高并发生产场景。解决方案：一是使用 Snowflake 平台（自动扩展）；二是用 Nginx + 多副本（每个副本运行一个 Streamlit 实例）；三是使用 st.fragment（v1.58+）让部分组件独立运行不阻塞整体页面。来源

初级用法

1. 显示 DataFrame：st.dataframe(df) 交互式表格，支持排序、搜索、列宽调整
2. 侧边栏布局：st.sidebar.slider("参数", 0, 100) 将控件放在侧边栏，主区域保持整洁
3. 条件显示：if st.checkbox("显示原始数据"): st.write(df) 让用户自主选择显示内容
4. 文件上传 + 处理：uploaded = st.file_uploader("上传 CSV"); if uploaded: df = pd.read_csv(uploaded)
5. 进度条：progress_bar = st.progress(0) 配合循环更新进度

高级玩法

1. 自定义组件：用 streamlit.components.v1.html() 嵌入自定义 HTML/JS，或开发 Streamlit 组件包（React 编写）
2. fragment 独立运行：@st.fragment 装饰后，该部分 UI 独立 rerun，不影响整体页面（v1.58+）
3. Session State 持久化：st.session_state["messages"] = [{"role": "user", "content": "你好"}] 实现多轮对话
4. 性能监控：集成 st.metric 实时展示 QPS、延迟等指标，配合 time 模块记录每次推理耗时
5. 动态表单：使用 st.form + st.form_submit_button 实现批量提交，避免每次控件变化都 rerun

小技巧

1. 使用 st.columns 布局：col1, col2 = st.columns(2) 实现左右分栏，比默认上下排列更美观
2. 隐藏默认菜单：st.set_page_config(menu_items=None) 去掉右上角的汉堡菜单，适合演示场合
3. 页面标题和图标：st.set_page_config(page_title="我的应用", page_icon="🤖") 第一行设置，浏览器标签更好看
4. 空占位符：placeholder = st.empty() 稍后用 placeholder.write("新内容") 更新，实现动态刷新
5. 全屏模式：使用 st.expander("详情") 折叠长内容，保持页面简洁

进阶学习建议

• 官方教程 30 Days of Streamlit：https://30days.streamlit.app 每天 10 分钟，30 天掌握全部功能
• 深入学习 session_state：理解 Streamlit 的 rerun 机制是高效开发的关键
• 探索 Streamlit Components：https://streamlit.io/components 社区组件库，扩展地图、3D、视频处理能力
• 部署实践：先在 Community Cloud 部署免费公开应用，体验 CI/CD 流程，再评估企业方案
• 阅读源码：Streamlit 的 ScriptRunner 实现非常优雅，了解其运行机制有助于规避性能陷阱

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

参考链接

• Streamlit 官网
• Streamlit GitHub
• Streamlit 文档
• Streamlit Community Cloud