来源：notes/documents/02_dg板卡X5_BPU推理服务_可视化HTML.md

dg 板卡 X5 BPU 推理服务：可视化 HTML 报告

日期：2026-09-19

这是一篇原生 Markdown 内嵌 HTML 的笔记：正文本身是一段自包含的 HTML（纯 <style> + <div>，无 JavaScript、无外部资源），嵌在 Markdown 里由博客渲染。它用图表的方式把整套 BPU 推理服务讲了什么、原理是什么、实测到什么，一次性呈现出来。

说明：飞书文档导入会丢弃 <div> / <style> 这类原生 HTML 标签（已实测确认），所以这篇只在博客侧渲染；文字版原理与代码见 notes/documents/01_dg板卡X5_BPU推理服务_原理_问答_代码.md。

附：原生 Markdown 嵌入 HTML 的实测结论

这次实验的目标是搞清楚「怎么把 HTML 放进 Markdown 里，并真的让别人看到」。

做法：把一整段自包含 HTML（<style> + <div>，无 JavaScript、无外部图片/字体/CDN）直接写在 Markdown 正文里。块级 HTML 标签必须顶格起行，中间不要用 Markdown 语法包裹它。

结论一：博客侧可以渲染（可用）。 博客是 Jekyll，_config.yml 里 markdown: kramdown + kramdown.input: GFM。kramdown 在 GFM 模式下会把块级原生 HTML 原样透传，不做转义。导入脚本 import_personal_assistant_notes.py 也只是把笔记原文照搬进 _posts/，没有任何 HTML 转义逻辑，所以内嵌 HTML 能一路走到最终页面。

结论二：飞书文档侧不能渲染（会丢）。 lark-cli docs +create --doc-format markdown 走的是飞书的 Markdown → 文档块转换，实测结果是：

所以同一篇笔记里混大量原生 HTML，会让飞书那边的文档变得很乱。这次的做法是拆成两篇：文字版走飞书 + 博客，HTML 可视化版只在博客。

结论三：Jekyll 的 Liquid 是隐藏地雷。 Jekyll 在 Markdown 渲染之前会先跑一遍 Liquid 模板引擎，所以正文里任何成对的双花括号（Liquid 的输出语法）或「花括号 + 百分号」（Liquid 的标签语法）都会在渲染前被当成模板求值，轻则内容消失、重则整站构建失败。写代码示例（尤其是嵌套字典字面量）或 CSS 时特别容易踩到。规避方式有两种：一是内容里干脆不出现这两个序列；二是用 Liquid 自带的 raw / endraw 标签把整段包起来，标签只对博客侧生效，飞书侧会看到标签本身。

结论四：必须无 JavaScript。 kramdown 对 <script> 的处理不稳定，而且博客正文里塞脚本既没必要也不安全。这次的可视化全部用纯 CSS 实现：分层图用带色边框的卡片 + <div>▼</div>，条形图用百分比宽度的 <i>，响应式用 @media。这样任何 Markdown 渲染器都不会把它拆坏。

可复用的模板骨架：

<style>
.viz-wrap{ /* 所有样式必须自带命名空间前缀，避免和博客主题冲突 */ }
</style>

<div class="viz-wrap" markdown="0">
  <h3>标题</h3>
  <p>正文……</p>
</div>

三个要点：样式类名加统一前缀（这次用 bpuv-）、markdown="0" 提示渲染器不要解析内部内容、整段 HTML 里不要出现成对的双花括号或 Liquid 标签语法。