大模型提示工程AI Agent【免费下载链接】guidanceA guidance language for controlling large language models.项目地址https://gitcode.com/gh_mirrors/gu/guidance点击查看免费下载导读stitch是 guidance 项目官方仓库中附带的一个 Jupyter Widget 包它提供一条JupyterPython 内核与 JavaScript 之间的双向通信通道Python 侧可以通过内核往页面里的 iframe 发送消息iframe 内的 JavaScript 也可以把消息传回内核从而在 Notebook 中嵌入可交互的 HTML/JS 界面并与之实时交换数据。读完本文你将掌握 stitch 的安装与前端扩展配置、StitchWidget的完整属性用法、基于postMessage的双向通信协议以及如何进行开发者模式安装与调试。一、stitch 是什么为内核 ↔ 页面搭建双向消息桥stitch 的核心定位一句话即可概括——Bidirectional comms for Jupyter and JavaScript.Jupyter 与 JavaScript 的双向通信。它不是一个通用的 UI 组件库而是一个纯通信层组件StitchWidget在 Notebook 输出区创建一个沙箱 iframe并以postMessage为媒介把 Python 内核的字符串消息转发进 iframe同时把 iframe 内产生的消息回传内核。这一点在 Python 侧类定义中写得非常直白Widget that purely handles communication between an iframe and kernel via postMessage. —— stitch/stitch.py从源码结构看该包由三部分协作组成组成部分仓库中的位置职责Python 侧 Widgetstitch/stitch.py定义StitchWidget及其同步属性作为内核侧收发消息的端口TypeScript 前端src/widget.ts渲染 iframe、监听message事件、在模型与 iframe 之间转发消息扩展注册入口stitch/init.py向 Jupyter 声明 labextension / nbextension 的安装路径需要特别说明的是缝合stitch只负责通信本身不限制 iframe 里运行什么内容。你可以把任意 HTML/JavaScript 塞进srcdoc属性由它负责解释和处理消息——这正是它适合在 guidance 这类语言模型项目中被用于渲染可视化界面的原因。二、安装 stitchpip / conda 两种方式1. 基础安装根据 docs/source/installing.rst 与 docs/source/index.rst最简单的方式是通过 pip 安装pip install stitch或通过 conda 安装conda install stitch仓库 README.md 中还提及包名guidance-stitch实际以当前发布渠道为准文档中 pip 与 conda 两种形式均已列出。2. 前端扩展配置重要stitch 是双端组件Python 包装好后前端扩展是否注册决定了 widget 能否真正渲染。文档给出如下判定规则使用 conda 安装时前端扩展通常已随包自动配置上述命令一般可以省略。使用 pip 安装且 Notebook 版本 5.3 时必须手动安装并启用前端扩展。如果是 classic Notebook区别于 JupyterLab运行jupyter nbextension install [--sys-prefix / --user / --system] --py stitch jupyter nbextension enable [--sys-prefix / --user / --system] --py stitch其中的--sys-prefix / --user / --system是互斥的三选一作用域标志用于决定扩展装到哪个环境在 conda 环境中通常应选择--sys-prefix以确保扩展落在当前虚拟环境对应的 Python 前缀下。如果是 JupyterLab则安装 lab 扩展jupyter labextension install guidance-ai/stitchguidance-ai/stitch这个前端包名与 Python 侧_frontend.py中声明的module_name完全一致见 stitch/_frontend.pyJS 包当前版本为0.1.5见 package.json。3. 扩展注册的底层依据为什么需要手动配扩展因为 Jupyter 通过约定函数发现前端资源。在 stitch/init.py 中定义了两个注册函数_jupyter_labextension_paths()返回{src: labextension, dest: guidance-ai/stitch}告诉 JupyterLab 从构建产物labextension目录复制文件到jupyter path/labextensions/guidance-ai/stitch_jupyter_nbextension_paths()返回{section: notebook, src: nbextension, dest: stitch, require: stitch/extension}告诉 classic Notebook 把nbextension目录安装到jupyter path/nbextensions/stitch并以stitch/extension作为 AMD 模块入口。可以看到nbextension 的入口模块正是仓库里的 stitch/nbextension/extension.js它通过requirejs.config把guidance-ai/stitch映射到nbextensions/stitch/index从而让 Notebook 页面能够加载到 widget 的模型/视图实现。这也是文档要求安装后必须 enable的原因——只有启用了扩展这一映射才会被注入页面。三、快速上手三分钟跑通内核 → 页面 → 内核的完整回路仓库自带的示例 Notebook examples/introduction.ipynb 演示了 stitch 的完整用法下面按它的步骤展开讲解。1. 创建 Widget 并注入页面 HTMLimport stitch w stitch.StitchWidget() w.srcdoc html style script window.addEventListener(message, function(event) { if (event.source window.parent) { if (event.data.type kernelmsg) { document.getElementById(msgview).innerHTML event.data.content; window.parent.postMessage({type: clientmsg, content: event.data.content}, *); // Save state for offline render window.parent.postMessage({type: state, content: event.data.content}, *); } else if (event.data.type init_state) { document.getElementById(msgview).innerHTML event.data.content; } } }); window.addEventListener(load, function(){ var prevHeight 0; setInterval(function() { var body document.body; var html document.documentElement; var height html.getBoundingClientRect().height if (height ! prevHeight html.checkVisibility()) { msg { type: resize, content: { height: height px, width: 100% } }; window.parent.postMessage(msg, *); prevHeight height; } }, 100); }); /script body style div MESSAGE: span idmsgview stylebackground-color: #90ee90;/span /div /body /html w.initial_width 100% w.initial_height auto display(w)这段代码做了三件事指定srcdociframe 内渲染的完整 HTML 文档其中内嵌的script负责监听来自父页面的消息设置初始尺寸initial_width 100%、initial_height autodisplay(w)把 widget 渲染进 Notebook 输出区示例输出的 MIME 类型为application/vnd.jupyter.widget-viewjson说明它被识别为标准的 Jupyter Widget v2 模型。注意 iframe 内脚本的职责分工收到kernelmsg类型消息时更新页面内容并回发两条消息clientmsg用于实时回传、state用于保存离线渲染状态收到init_state时恢复上次的状态页面加载后用setInterval每 100ms 检查一次页面高度变化并发送resize消息实现 iframe 高度自适应内容。2. 从内核发送消息w.kernelmsg A language model is a probabilistic model of a natural language. ...给kernelmsg属性赋值后消息会经 traitlet 同步机制推送到前端前端再把消息 postMessage 进 iframe页面中的msgview立即更新同时clientmsg/state回传内核。3. 在内核侧观察回传消息w.observe(lambda x: print(x[new]), kernelmsg) w.kernelmsg Wow, a change!输出Wow, a change!observe是 ipywidgets traitlet 的观察接口这里既演示了内核侧对属性变化的响应也演示了属性被回写后如 iframe 回传的clientmsg、state可以在 Python 侧通过同样的机制捕获。示例的最终 widget 状态里clientmsg、state均为Wow, a change!证明了一次完整的内核 → iframe → 内核回路已经打通。四、StitchWidget 核心属性详解StitchWidget是ipywidgets.DOMWidget的子类所有通信字段都通过traitlets.Unicode定义并标记syncTrue意味着它们会在 Python 模型与前端 JS 模型之间自动同步见 stitch/stitch.py。各属性如下属性默认值说明kernelmsg内核 → 客户端消息通道。Python 侧赋值后前端会把内容以kernelmsg消息 postMessage 进 iframeclientmsg客户端 → 内核消息通道。iframe 内发送clientmsg消息后回写此属性srcdocpsrcdoc should be defined by the user/piframe 渲染的 HTML 源码赋值后前端会重建 iframe 的srcdoc并立即补发最新的kernelmsginitial_height1pxiframe 初始高度 CSS 值如autoinitial_width1pxiframe 初始宽度 CSS 值如100%initial_border0iframe 初始边框 CSS 值state状态快照字段用于保存/恢复界面状态如离线渲染场景对应的默认值在 TypeScript 前端 src/widget.ts 的defaults()中逐项一致Python 与 JS 两侧保持同步。单元测试 stitch/tests/test_example.py 也验证了空实例的默认行为kernelmsg 、clientmsg 、srcdoc psrcdoc should be defined by the user/p。五、双向通信协议前端到底在转发什么如果想深度定制 iframe 内的交互逻辑就必须理解前端StitchView处理的消息类型。查看 src/widget.ts 的recvFromClient回调与render()逻辑可以梳理出完整的消息清单父页面widget 前端接收 iframe 发来的消息消息类型type载荷content前端行为init_stitch无iframe 就绪信号触发初始化流程首次渲染时会依次发送init_state与当前kernelmsgclientmsg任意字符串写入模型clientmsg属性并save_changes()同步回内核resize{height, width}动态调整 iframe 的宽高 CSS用于自适应内容高度state任意字符串写入模型state属性并同步回内核父页面发送给 iframe 的消息消息类型type触发时机init_statewidget 初始化完成且模型非新建状态时向 iframe 恢复上次的state见emit_init_state()kernelmsg内核侧kernelmsg变化时change:kernelmsg回调或srcdoc更新后立即补发一次此外render()中还有两个值得注意的实现细节沙箱安全iframe 被显式加上sandbox且只放开allow-scriptssrc/widget.tsiframe 内的脚本可以运行但无法访问父页面 DOM从机制上隔离了页面与 Notebook 环境事件过滤所有message事件都先校验event.source iframe.contentWindow确保只处理来自本 widget iframe 的消息避免被页面中其他来源的 postMessage 干扰。对应地StitchModel在 src/widget.ts 中声明了与 Python 侧完全一致的_model_name: StitchModel、_view_name: StitchView模块名取自 src/version.ts保证了模型注册的双端匹配。六、开发者模式安装与调试如果要在本地修改 stitch 源码尤其是前端 TypeScript 代码按照 docs/source/develop-install.rst 的流程操作。1. 克隆仓库并以可编辑模式安装git clone https://github.com/guidance-ai/stitch cd stitch pip install -e .2. 链接安装前端扩展如果同时开发 JS/前端代码需要对扩展做符号链接symlink安装这样源码改动即时生效无需反复复制classic Notebookjupyter nbextension install [--sys-prefix / --user / --system] --symlink --py stitch jupyter nbextension enable [--sys-prefix / --user / --system] --py stitchJupyterLabjupyter labextension install .3. 构建与热更新仓库 package.json 提供了完整的构建脚本体系jlpm run build依次执行 TypeScript 编译tsc、webpack 打包 nbextension、以及 dev 模式的 labextension 构建jlpm run watch并行启动tsc -w、webpack --watch与jupyter labextension watch .配合jupyter lab即可实现前端改动自动重建、浏览器刷新即生效Python 侧改动则需重启 Notebook 内核才能生效这一点在 README.md 中有明确说明。值得一提的是开发依赖中把jupyterlab/builder钉在 4.0.11、并在jupyterlab.sharedPackages中将jupyter-widgets/base标记为bundled: false, singleton: true见 package.json这是为了让 lab 扩展与 Notebook 共享同一份 widget 基础库避免模型注册冲突——在排查widget 不显示类问题时可优先检查这一依赖对齐关系。七、验证与常见问题排查1. 用单元测试验证默认行为仓库在 stitch/tests/test_example.py 提供了最小化的验证用例from ..stitch import StitchWidget def test_example_creation_blank(): w StitchWidget() assert w.kernelmsg assert w.clientmsg assert w.srcdoc psrcdoc should be defined by the user/p该用例确认了StitchWidget()无参创建时的默认状态可作为开发时回归测试的模板。2. 常见问题定位思路widget 只显示为空白先确认扩展是否已启用。classic Notebook 运行jupyter nbextension listJupyterLab 运行jupyter labextension list检查stitch/guidance-ai/stitch是否在列pip 安装且 Notebook 5.3 时必须手动执行第二节中的 install enable 命令。内核消息发不进 iframe检查srcdoc内是否监听了kernelmsg类型且事件源校验为event.source window.parent同时确认 iframe 脚本是在init_stitch握手之后才运行前端只在收到该信号后才开始推送消息。iframe 高度异常利用resize协议参照示例在 iframe 内周期性比较内容高度并回传{type: resize, content: {height, width}}。Python 收不到回传确认 iframe 回发的是clientmsg/state类型且内容为可序列化字符串这两个属性与kernelmsg、srcdoc一样都依赖 traitlets 的syncTrue双向同步链路。八、小结stitch 以极简的设计解决了 Jupyter 生态中的一个关键痛点让任意 HTML/JavaScript 界面与 Python 内核之间拥有可靠的实时双向消息通道。它的使用路径清晰——pip/conda 安装、按环境配置前端扩展、用StitchWidget的几个字符串属性完成收发它的原理同样清晰——DOMWidget traitlets 同步属性 沙箱 iframe postMessage协议。无论是做交互式可视化、嵌入式工具面板还是在语言模型工作流中渲染动态结果这套模式都可以直接复用。进一步阅读完整安装说明见 installing.rst开发安装说明见 develop-install.rst可运行示例见 introduction.ipynbPython 与前端实现分别见 stitch.py 与 widget.ts。赞分享大模型提示工程AI Agent【免费下载链接】guidanceA guidance language for controlling large language models.项目地址https://gitcode.com/gh_mirrors/gu/guidance点击查看免费下载相关推荐AMD量化模型生产部署终极指南企业级应用场景与最佳实践 AMD量化模型生产部署终极指南企业级应用场景与最佳实践 在当今AI快速发展的时代 AMD量化模型生产部署 已成为企业降低推理成本、提升效率的关键技术。大模型提示工程AI Agent终极指南如何在pywebview中实现JavaScript与Python双向通信终极指南如何在pywebview中实现JavaScript与Python双向通信 想要为你的Python应用构建现代化GUI界面pywebview正是你需要桌面应用前端Kedro 与 Jupyter Notebook 双向集成实战渐进式迁移与项目内实验完整指南Kedro 与 Jupyter Notebook 双向集成实战渐进式迁移与项目内实验完整指南 本指南基于 Kedro 官方文档的 Notebooks 与 IP数据工程工作流自动化上一篇SiYuan 加密笔记本深度解析本地数据加密、密钥管理与隐私保护完全指南下一篇【免费下载】 DeepCAD 开源项目教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考