Genkit Python 开发工作流实战：genkit start、Dev UI 与 trace 全链路调试指南

Genkit Python 开发工作流实战genkit start、Dev UI 与 trace 全链路调试指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skillsGenkit Python 的日常开发调试核心不在于跑通代码而在于看得见每一次模型调用。本指南以 dev-workflow.md 为骨架完整讲解从 Gemini API Key 准备、依赖安装、genkit start启动 Dev UI、在 Dev UI 中执行 flow到用flow:run与 trace 命令做非交互式验证的整套开发流程并补充仓库内源码级佐证与常见坑位。读完你就能掌握一套可复制、可落地的 Genkit Python 应用调试方法论。一、为什么调试 Genkit 应用必须走 Dev WorkflowGenkit Python 应用flow、agent、tool、embedding 等运行时会产生大量可观测信息prompt 内容、模型输入输出、工具调用记录、token 消耗、延迟与错误。这些信息只有通过 Genkit 的 trace 机制才能完整捕获。关键结论来自仓库文档的明确说明直接uv run运行应用会跳过 trace 采集等于盲调见 SKILL.md 的 Genkit CLI (recommended) 一节。而genkit start采用非侵入式包装——它按原样运行你的 Python 程序同时捕获每一个 Genkit action 的 trace让你可以从终端或 Dev UI 中证明工具确实被调用、检查模型的输入输出甚至在无头headless环境下完成校验。它还转发 stdio因此依赖 stdin/stdout 的交互式 CLI 工具也能正常工作。本指南对应的协作约定是代码生成完成后始终把以下三件事交给开发者而不是代为执行完整的运行前检查清单含可直接复制的绝对路径命令在开发者终端中前台运行的genkit start命令预期它会阻塞分步的 Dev UI 操作说明让开发者无需猜测即可测试。二、Step 13运行前检查清单在启动 Dev UI 之前按顺序完成以下三步准备。1. 获取 Gemini API Key如果开发者还没有 API Key前往 Google AI Studio 的 API Key 页面点击Create API key并复制。这是后续所有命令的前提。2. 设置环境变量GEMINI_API_KEY在终端中执行临时生效export GEMINI_API_KEYyour-api-key-here如需跨会话持久化追加到 shell profile 并立即生效示例为 zshecho export GEMINI_API_KEYyour-api-key-here ~/.zshrc source ~/.zshrc注意仓库文档中使用的模型 ID 均带前缀例如googleai/gemini-flash-latest而不是裸的gemini-flash-latest这是常见的出错点之一见 common-errors.md。3. 安装依赖将/path/to/your-project替换为项目实际绝对路径例如/Users/yourname/projects/my-genkit-appcd /path/to/your-project uv add genkit genkit-google-genai前提是项目包含pyproject.toml空目录下先执行uv init即可。关于项目初始化的完整细节虚拟环境、requires-python 3.10、最小化pyproject.toml示例、可选插件如genkit-middleware/genkit-fastapi/genkit-evaluators见 setup.md。建议始终使用项目级.venv不要安装到系统解释器。三、Step 4启动 Dev UIgenkit start准备工作完成后在终端前台运行cd /path/to/your-project GEMINI_API_KEYyour-api-key-here genkit start -- uv run src/main.py这条命令会阻塞终端——这是预期行为。保持该终端打开供 Dev UI 持续运行。启动成功后你会看到类似输出Genkit Tools UI: http://localhost:4000此时 Dev UI 已在http://localhost:4000运行。停止方式在终端按CtrlC。关于genkit start的机制值得展开说明依据 SKILL.md 与 dev-workflow.md 的 CLI 章节它非侵入式地包装任何使用 Genkit 库的 Python 程序程序本身无需改动它会捕获程序运行期间所有 Genkit action 的 trace无论这些调用是由 Dev UI 触发、由你自己的 Web 服务/前端触发还是由纯脚本触发它转发 stdio所以交互式 CLI 工具不受影响genkit start会一直运行直到你CtrlC停止这对于供 Web/移动端调用的常驻服务或你自己退出交互式 CLI都是正确且符合预期的行为。两个常用变体genkit start --noui -- uv run src/main.py # 同前但不开 Dev UI仍是常驻服务 genkit start --non-interactive -- uv run src/main.py # 全局标志跳过首次运行分析通知等交互提示注意--noui只是去掉 Dev UI不是一次性命令不会自行退出--non-interactive必须在--之前使用让 CLI 采用默认值、绝不阻塞在提示上例如首次运行的 analytics 通知它也适用于flow:run。如果你用 FastAPI 提供服务同样的启动方式即可在 Dev UI 中调试 HTTP 端点GEMINI_API_KEYyour-key genkit start -- uv run src/main.py等待 CLI 打印Genkit Developer UI: http://localhost:4000若 4000 被占用端口会不同完整示例见 fastapi.md 的 Run with Dev UI 一节。四、Step 5在 Dev UI 中测试 flow启动后按以下步骤操作浏览器打开http://localhost:4000点击左侧边栏的Run按名字找到你的 flow例如summarize、chat、joke_generator在输入框中以 JSON 粘贴输入例如{text: hello world}点击Run按钮右侧即出现输出点击左侧边栏的Traces检查每一步执行、模型调用、token 数、延迟。输入 JSON 的结构与 flow 的参数 schema 对应。例如在 examples.md 中summarizeflow 的入参是 Pydantic 模型SummarizeInput(BaseModel): text: str因此在 Dev UI 中输入{text: ...}即可命中该字段。结构化输出、流式 flow 等模式也在该文档中给出了可直接复制的实现供你在 Dev UI 中逐一验证。五、CLI 命令全解从常驻服务到一次性验证除了 Dev UIGenkit CLI 还提供一组面向终端的高效命令覆盖常驻调试与非交互式验证两种场景。5.1 常驻调试genkit start -- 你的运行命令标准姿势是为你的常规运行命令加上genkit start --前缀。这样无论触发来源是 Dev UI、自己的 Web 服务还是普通脚本任何 Genkit 代码产生的遥测都会被采集genkit start -- uv run src/main.py genkit start --noui -- uv run src/main.pygenkit start是长驻进程适合常驻服务器与交互式 CLI不要在自动化/非交互上下文中把它当作阻塞步骤使用那种场景请用下面的flow:run。5.2 一次性执行genkit flow:run按名字调用某个 flow--之后追加运行命令以启动运行时命令按原样执行以注册你的 flowgenkit flow:run myFlow {data: input} -- uv run src/main.pyflow:run是自终止的它只运行一次 flow、打印一个Trace ID然后退出因此非常适合快速的、非交互式的检查与genkit start的常驻行为形成互补。该命令产生的 trace 可用 5.3 中的 trace 命令查看。一个必须牢记的边界flow:run只能运行flowai.flow()装饰的函数不能直接运行 agentai.define_agent定义的对象。如果要通过 CLI 验证一个 agent需要把单个回合包装进一个一次性 flow 再运行agents.md 的 Verify an agent from the CLI 一节给出了现成示例ai.flow() async def try_weather_agent(message: str) - str: return (await agent.chat().send(message)).text # genkit flow:run try_weather_agent Weather in Tokyo? -- uv run src/main.py5.3 用 trace 调试最快的排障路径trace 是查看 prompt、模型输入输出、工具调用、延迟和错误的最快方式。在genkit start下运行任意程序后从终端执行genkit trace:list # 列出最近的 trace ID genkit trace:get traceId # 完整 trace 详情输入、输出、工具调用、错误 genkit trace:get traceId --format json # 机器可读 JSON可安全地管道给 jq 等解析器要点需要机器可读输出时务必加--format json否则拿到的是干净的 JSON默认输出面向人类横幅/日志行大 trace 可能被截断不适合直接管道处理——要用--format json、grep 或 Dev UI 的 trace 查看器。5.4 文档查询在终端里检索官方文档genkit docs:search streaming python genkit docs:list python genkit docs:read python/flows.md这三个命令让你不必离开终端就能检索、列出并阅读 Genkit Python 的官方文档适合在编码过程中即时查证。六、自动化与 CI 场景选对命令综合上述行为差异自动化场景的选型原则可以归纳为需要一次性、可终止的验证→ 用genkit flow:run自终止、打印 Trace ID需要常驻服务/交互式 CLI→ 用genkit start前台运行、CtrlC 停止完全无交互环境Agent/CI→ 给命令加全局--non-interactive标志避免阻塞在首次运行提示上不要把genkit start作为自动化流水线里的阻塞步骤。七、常见问题排查以下问题与修复均来自 dev-workflow.md 的 Troubleshooting 章节可直接对照执行genkit: command not found— 先安装全局 CLInpm install -g genkit-cliGEMINI_API_KEY not set— 执行export GEMINI_API_KEYyour-key并参考第二节的持久化写法端口 4000 被占用— 换端口启动genkit start --port 4001 -- uv run src/main.pyuv: command not found— 安装 uv 后重试官方安装脚本curl -LsSf https://astral.sh/uv/install.sh | shDev UI 中看不到 flow— 检查genkit start启动输出是否有报错。在genkit start之下还有一些高频坑位值得提前规避详见 common-errors.md事件循环问题长时间运行的应用务必通过ai.run_main(main())进入SKILL.md 的工作流也要求 Genkit 应用尤其是genkit start下使用ai.run_main入口模型 ID 缺前缀必须写googleai/gemini-flash-latest流式句柄不要 await 错对象ai.generate_stream(...)返回的 handle 不要直接 await应该async for chunk in sr.stream后await sr.response工具参数必须包 Pydantic 模型裸的str/float参数在 Gemini 上会报 400用ai.tool()而非ai.define_tool()。八、从跑通到可验证Dev Workflow 的定位回顾整条链路uv init建项目setup.md→ 用ai.flow()/ai.define_agent()编写功能examples.md、agents.md→genkit start -- uv run src/main.py启动并采集 trace → Dev UI 或flow:run/trace:get验证结果 → 出错时按 common-errors.md 对照排查。Dev Workflow 的价值在于把调试盲区变成全链路可视无论是 prompt 是否正确、工具是否真的被调用、还是某次调用花了多少 token、多慢、是否报错都能在 Dev UI 的 Traces 面板或终端的trace:get输出中一目了然。把这套流程固化为日常习惯Genkit Python 应用的开发效率与可维护性会得到质的提升。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考