从Gradio切换到Streamlit迁移本地模型展示组件时遇到的版式差异处理

文章导读
迁本地模型展示组件时,最先暴露的问题往往不是推理接口,而是界面布局规则。Gradio 的 UI 组件默认会把可用宽度撑满,Streamlit 则按脚本顺序往下推流,组件宽度和间距都有自己的一套默认值。如果只把输入输出函数搬过来,页面会显得松散,列宽也对不上。下面按判断、处理、验证的顺序整理。
📋 目录
  1. 一 先别急着改配置:从 Blocks 布局判断工作量
  2. 二 图像输出:st.image 的宽度参数要统一
  3. 三 原生组件缺失:用 st.markdown 拼接 HTML 前想清楚
  4. 四 数据表格和间距:st.dataframe 不是 Gradio 的 Dataframe
  5. 五 改完后看这几个信号
A A

迁本地模型展示组件时,最先暴露的问题往往不是推理接口,而是界面布局规则。Gradio 的 UI 组件默认会把可用宽度撑满,Streamlit 则按脚本顺序往下推流,组件宽度和间距都有自己的一套默认值。如果只把输入输出函数搬过来,页面会显得松散,列宽也对不上。下面按判断、处理、验证的顺序整理。

先别急着改配置:从 Blocks 布局判断工作量

判断版式是否需要重写,重点看原Gradio应用是否使用了Blocks的显式布局。若只是简单的输入输出单列流程,Streamlit默认的流式布局可以无缝承接;但一旦存在gr.Row和gr.Column嵌套,Streamlit的st.columns按比例分配宽度,却不像Gradio那样自动填充剩余空间,容易出现列宽与预期不符。建议先梳理原应用的分块层次,再决定采用st.sidebar、st.columns还是st.container来重建。

这里说的“梳理分块层次”是指把原 Gradio 界面按行拆开,记录每一行里有几个列,列内又包含哪些组件。Streamlit 的 st.columns 是按数字列表分配相对比例的,例如下面这个三栏布局,只能保证左右栏相对中栏是 1:2,不会像 Gradio 那样由内容撑开宽度。

left, mid, right = st.columns([1, 2, 1])
with left:
    st.text_input('模型ID')
with mid:
    image_placeholder = st.empty()
with right:
    st.caption('日志区域')

这段代码用于把 Gradio 的 gr.Row 映射成 Streamlit 的水平排列。执行位置在页面渲染逻辑里,放在模型推理函数之前。验证方式是在浏览器里拖动窗口宽度,看三列是否按比例变化;如果某一列内容被挤压,优先检查该列内组件是否设置了固定的 width 或 max-width。

图像输出:st.image 的宽度参数要统一

对于本地模型展示组件,图像类输出是最容易因版式差异引起视觉混乱的部分。在Gradio中gr.Image通常按原图比例展示,且可在组件内调节高度;迁到Streamlit后,改用st.image时需要显式传入width参数,或设置use_container_width=True让图宽跟随容器。注意两种方式不能混用,否则不同图片会以不同基准对齐。如果希望维持固定输出尺寸,建议先裁剪或缩放图像,再通过st.image以固定宽度渲染。

从Gradio切换到Streamlit迁移本地模型展示组件时遇到的版式差异处理

实际操作中,先统一“基准”。如果页面里大部分图片要填满容器,就所有图片都用 use_container_width=True;如果希望每张图宽度一致,就在传给 st.image 之前把图像固定到同一尺寸。下面的示例固定为 512 像素宽度,避免不同模型输出尺寸不一致导致错位。

from PIL import Image

img = Image.open('output.png')
img = img.resize((512, 512))
st.image(img, use_container_width=False, width=512)

注意 use_container_width 参数在部分 Streamlit 版本里写作 use_column_width,迁移前先确认当前版本。验证方式是检查同一行多张图片的左边缘和右边缘是否对齐;如果有的图靠左、有的图居中,优先检查是不是混用了 width 和 use_container_width。

原生组件缺失:用 st.markdown 拼接 HTML 前想清楚

需要特别留意组件库差异带来的隐藏风险。Gradio提供原生的HighlightedText、Label等展示组件,而Streamlit原生没有对应组件,通常要用st.markdown拼接HTML或引入第三方组件,这会引入额外依赖,并可能因Markdown渲染沙箱导致自定义样式失效。如果项目对展示版式要求严格,应预先评估是否有必要用第三方组件,或改用表格和文本组合来替代,避免在迁移后期被样式问题拖住。

从Gradio切换到Streamlit迁移本地模型展示组件时遇到的版式差异处理

例如要给文本中的实体标色,Streamlit 没有内置高亮组件,常见的做法是先拼一段 span 标签再交给 st.markdown。下面这段代码在本地通常能显示红色文字,但要注意必须传入 unsafe_allow_html=True。

st.markdown("<span style='color: #d14'>异常</span> 的推理结果", unsafe_allow_html=True)

这段代码的局限在于:Streamlit 的 Markdown 渲染沙箱会过滤部分 HTML 属性,如果发现颜色不生效,优先检查是否漏了 unsafe_allow_html=True,再确认标签属性被保留。如果项目对排版要求高,建议用 st.dataframe 或 st.table 做结构化展示,而不是依赖 HTML 片段。

数据表格和间距:st.dataframe 不是 Gradio 的 Dataframe

迁移数据表格时,另一个容易误判的地方是 st.dataframe 的默认行为。Gradio 的 Dataframe 默认紧凑显示,行列自适应内容;Streamlit 的 st.dataframe 则内置了排序、列宽拖拽和滚动条,即使数据量不大,也会额外占满整行高度。如果仅用于展示,可以用 st.table 保持紧凑,但 st.table 不支持大数据量。另外,Streamlit 组件间有统一间距,Gradio 组件间默认无额外间距,迁移后页面会明显变散,需要适当调整 padding 或采用容器合并区域。

这里需要按数据量和使用目的做决定:用户需要排序或筛选时保留 st.dataframe,否则换成 st.table。两种写法如下。

从Gradio切换到Streamlit迁移本地模型展示组件时遇到的版式差异处理
st.dataframe(df, use_container_width=True)  # 可排序、拖列宽
st.table(df)                                 # 紧凑、静态

验证方式是看表格是否出现不必要的滚动条。如果数据只有几十行却出现纵向滚动条,且页面里还有大块空白,优先改用 st.table。间距问题可以在列容器里用 st.markdown 注入少量 CSS 调整 padding,但要注意 CSS 会全局生效,改完立即查看侧栏布局是否受影响。

改完后看这几个信号

迁移完成后,先用浏览器开发者工具逐项检查容器宽度和边距。对比时保持两边浏览器视口一致,否则宽度差异会误导判断。Streamlit 的侧栏与主区域之间没有明显的物理分隔,检查时应重点看列之间是否出现意外的重叠或空白。可以临时给 st.columns 加边框标记边界,例如用 st.markdown 注入一段 CSS,只给 data-testid 为 stColumn 的元素加 1px 红色边框,确认行列顺序后再移除调试样式。

如果发现列之间重叠,优先检查 st.columns 比例和列内元素的固定宽度;如果空白过多,考虑用 st.container 把相邻组件合并成一个区域,或者用 st.expander 折叠低频操作。最后保留旧 Gradio 应用的启动脚本作为回滚点。版式问题只在前端层处理,如果改列宽无法对齐,不要为了对齐去修改模型输出尺寸,那样会影响后续推理逻辑。