Genkit Python 官方样本指南：用 uv 跑通 22 个可运行示例（py/samples）
发布时间：2026/9/17 12:06:54 作者：尧图编辑部 阅读量：1,286
Genkit Python 官方样本指南用 uv 跑通 22 个可运行示例py/samples【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkitGenkit 是一个用于构建 agentic 应用的开源框架其 Python SDK 的py/samples/目录收录了 22 个“今晚就能跑”的示例应用每个文件夹都以它所演示的特性命名。读完本文你将掌握统一的uv syncuv run运行流程、各样本的前置条件API Key / 云凭据 / 本地服务、带 Dev UI 观测的运行方式以及 fastapi-bugbot、tracing、agents 等旗舰样本背后的源码实现可以直接照着命令在自己的环境里跑起来。一、样本目录的组织方式以特性命名独立成项目py/samples/README.md 对这批样本的定位只有一句话“Snippets you can run tonight. Most needGEMINI_API_KEY.”今晚就能跑的代码片段多数需要GEMINI_API_KEY。官方还给出了两条导航建议如果你日常使用 FastAPI从fastapi-bugbot开始其余文件夹都以“展示的特性”命名按名字找例子即可。从仓库结构看每个样本都是一个独立的 uv 项目目录内有一个 pyproject.toml 声明依赖genkit加上对应的插件包如genkit-google-genai、genkit-fastapi入口统一放在src/main.py。以 fastapi-bugbot 的 pyproject.toml 为例其依赖为genkit、genkit-fastapi、genkit-google-genai、python-dotenv、uvicorn[standard]且requires-python 3.10——这也对应了 py/README.md 中对整个 Python SDK 的要求Python 3.10。二、统一运行流程三步跑通可选 Dev UI 观测标准三步文档给出的核心运行方式如下cd py/samples/name uv sync uv run src/main.pyuv sync读取该样本的pyproject.toml创建虚拟环境并安装锁定的依赖。每个样本相互隔离不会互相污染依赖版本uv run src/main.py在项目环境内执行入口脚本。大多数样本在运行前需要先导出 API Key以 Gemini 为例export GEMINI_API_KEYyour-api-key带 Dev UI 的观测运行原文档给出的第二条命令用于在运行时查看 tracesgenkit start -- uv run src/main.pygenkit start会启动 Genkit Developer UI默认运行在http://localhost:4000。启动后可以直接调用已注册的 flow 和 agent并在 Traces 标签页中查看每一步产生的 span。tracing 样本的 README 就演示了这个流程运行后打开http://localhost:4000在 Dev UI 中运行triage_ticket工单分派的每一步账号查询、三次模型调用都会作为独立 span 出现在 trace 里。三、22 个样本全景能力、前置条件与入口下表汇总了 py/samples/ 下全部样本的主题与运行前提“无 Key”表示不需要任何 API Key 即可运行样本展示能力前置条件basic-flowsFlowtyped、traced、streamable 的函数无 Key 可跑promptsprompts/*.prompt模板文件与代码解耦GEMINI_API_KEYoutput-formatsoutput_schema结构化输出、generate_stream流式分块GEMINI_API_KEYcontextuser/tenant 上下文透传到generate()与工具GEMINI_API_KEYfastapi-bugbotFastAPI serve_flow 并行generate()GEMINI_API_KEYflask-hello在现有 Flask 应用上挂载 flowGEMINI_API_KEYdjango-hello把 flow 作为 Django 视图SSE 流式返回GEMINI_API_KEYmiddlewareai.generate(..., use[...])中间件如邮箱脱敏GEMINI_API_KEYmiddleware-coding-agent沙盒 workspace 编码 agent写操作暂停等 y/N 确认GEMINI_API_KEYmultipart-tools工具返回值包装 vsresponse(...)带媒体返回GEMINI_API_KEYtool-interrupts工具中断restart_tool/respond_to_interruptGEMINI_API_KEYanthropic-sampleClaude 走同一个generate()ANTHROPIC_API_KEYamazon-bedrock-sampleBedrockNova Lite、Titan Embed走 AWS profileAWS_PROFILE、AWS_REGION并在控制台开通模型访问ollama-sample本地 Ollamachat、流式、工具、embeddings本地 Ollama 服务ollama serve并 pull 模型gemini-code-executionGemini 生成并执行 Python 代码GEMINI_API_KEYgemini-context-caching上下文缓存第二次调用输出cached_content_tokensGEMINI_API_KEYgoogle-genai-deep-research后台 Deep Research 作业generate_operation()check_operation()GEMINI_API_KEYgoogle-genai-media语音/图像走 Google AI视频走 VertexVertexAI.veo_modelGEMINI_API_KEY gcloud auth application-default loginvertexai-imagenVertex AI 图像生成用 ADC 而非 Gemini KeyGOOGLE_CLOUD_PROJECT gcloud ADCtracing每个步骤一个 spanDev UI 与 Cloud TraceGEMINI_API_KEYevaluators内置 regex 评估器与自定义 judge 评估器regex 无需 Keymaliciousness 数据集需 GEMINI_API_KEYagents实验性 Agentdefine_agent 会话存储GEMINI_API_KEY其中入口脚本并非全部是src/main.pydjango-hello通过uv run uvicorn myproject.asgi:application --port 8080启动evaluators走genkit eval:run命令agents的编号脚本在basic/下、FastAPI 进程在testapp/server.py。下文第四节会单独说明这几个例外。四、旗舰样本的源码级解读fastapi-bugbot三个并行generate() 结构化 JSONfastapi-bugbot 是一个 FastAPI 应用对一段代码从安全、bug、风格三个维度做审查返回结构化 JSON。入口文件 src/main.py 的关键实现ai Genkit( plugins[GoogleAI()], modelGoogleAI.gemini_model(gemini-flash-latest), ) class Analysis(BaseModel): issues: list[Issue] Field(default_factorylist) ai.flow() async def review_code(input: CodeInput) - Analysis: # 三个聚焦调用并行跑一个审查不阻塞其他两个 security, bugs, style await asyncio.gather( ai.generate(promptfFind security issues in this {input.language} snippet:\n{input.code}, output_schemaAnalysis), ai.generate(promptfFind bugs ..., output_schemaAnalysis), ai.generate(promptfFind style issues ..., output_schemaAnalysis), ) ...几个值得注意的点output_schemaAnalysis是 Pydantic 模型模型必须“填满”这个结构result.output直接拿到校验后的对象asyncio.gather并发发出三次generate()任一维度慢都不拖慢整体serve_flow(review_code, base_path/review)把 flow 挂成 HTTP 路由uvicorn 绑定127.0.0.1:8080。启动后用 curl 验证Swagger 文档在http://localhost:8080/docsexport GEMINI_API_KEYyour-api-key uv sync uv run src/main.pycurl -X POST http://localhost:8080/review \ -H Content-Type: application/json \ -d {data:{code:eval(user_input),language:python}}basic-flows无 Key 也能跑的 Flow 三件套basic-flows/src/main.py 演示了 flow 的三个核心属性且不需要模型与 API Keyai.flow() async def welcome(name: str) - str: async def lookup() - str: return fcustomer: {name} found await ai.run(namelookup, fnlookup) # 具名步骤 独立 span ... ai.flow(chunk_typeStatusChunk) async def status(count: int, ctx: ActionRunContext) - str: for i in range(count): await ctx.send_chunk(StatusChunk(stepi 1, labelworking)) # 流式进度 ... ai.flow() async def whoami(name: str, ctx: ActionRunContext) - str: return f{name} as {ctx.context} # 请求上下文经 ctx.context 注入ai.run(name..., fn...)为普通代码块命名使其在 trace 中成为独立 spanctx.send_chunk(...)的每个分块会被 Dev UI 和 HTTP 流渲染为进度whoami通过serve_flow(whoami, context_dependencycaller)挂载把 FastAPI 请求头里的鉴权信息转成ctx.context——请求上下文走独立通道而不是额外参数。tracing从 span 到 Cloud Tracetracing/src/main.py 的triage_ticketflow 里一次“账号查询”用ai.run(namelookup_account, ...)显式命名与模型调用并排出现在同一条 trace 中——当回复内容不对时这就是排查的第一现场。README 还给出了后续接入 Cloud Trace 的方式from genkit_google_cloud import enable_google_cloud_telemetry enable_google_cloud_telemetry(project_idmy-project)agents实验性会话存储是唯一差异agents 样本 明确标注 Agents 为实验性功能实例需从genkit.exp导入from genkit.exp import Genkit, InMemorySessionStore运行入口是basic/下按编号组织的脚本从 01 开始看cd py/samples/agents uv sync genkit start -- uv run basic/01_define_agent_with_store.py01_define_agent_with_store.py 的核心思路是“store 是唯一事实来源”store InMemorySessionStore() agent ai.define_agent( nameweatherAgent, modelGoogleAI.gemini_model(gemini-flash-latest), systemWeather assistant. Use getWeather for weather questions., tools[get_weather], storestore, )样本用InMemorySessionStore以便只凭GEMINI_API_KEY本地运行部署时把同一个store槽位换成genkit_google_cloud.exp里的FirestoreSessionStore()即可让会话在重启后仍能被load_chat(snapshot_id...)恢复。testapp/则是一个把这些 agent 通过serve_agent挂载在/api/name的 FastAPI 进程详见 testapp/README.mdDev UI 在http://localhost:4000、HTTP 在http://localhost:8080。五、特殊运行方式evaluators、django 与 ollamaevaluators评估器。内置 regex 评估器不需要 Key自定义 judge 评估器则是define_evaluatorgenerate()。README 给出的两条命令# 无需 API Key genkit eval:run datasets/genkit_eval_dataset.json --evaluatorsgenkitEval/regex -- uv run src/main.py # 需要 GEMINI_API_KEY genkit eval:run datasets/maliciousness_dataset.json --evaluatorsbyo/maliciousness -- uv run src/main.py其中genkitEval/regex是内置评估器引用byo/maliciousness是样本自定义的评估器。django-hello。把 flow 作为 Django 视图入口不是src/main.py而是 uvicorn 启动 ASGI 应用export GEMINI_API_KEYyour-api-key uv sync uv run uvicorn myproject.asgi:application --port 8080curl -N -X POST http://localhost:8080/chat \ -H Content-Type: application/json \ -H Accept: text/event-stream \ -H Authorization: beginner-demo \ -d {data:{name:Mittens}}ollama-sample。完全本地运行本地安装并启动 Ollama 后ollama pull llama3.2与ollama pull nomic-embed-text再执行标准的uv syncuv run src/main.py若服务不在127.0.0.1:11434设置OLLAMA_HOST。google-genai-deep-research。用generate_operation()发起后台 Deep Research 作业再用check_operation()轮询完整报告可能需要数分钟README 建议直接在 Dev UI 中运行 flowdeep_research并持续轮询。支持的模型在 flow 输入中设置modelgoogleai/deep-research-preview-04-2026googleai/deep-research-max-preview-04-2026googleai/deep-research-pro-preview-12-2025六、运行前提与端口约定小结Python 版本所有样本requires-python 3.10与 py/README.md 声明的 Python 3.10 一致凭据分三档无需任何 Keybasic-flows、evaluators的 regex 数据集只需GEMINI_API_KEY大多数样本其他凭据ANTHROPIC_API_KEYanthropic、AWS_PROFILE/AWS_REGIONbedrock、GOOGLE_CLOUD_PROJECTgcloud auth application-default loginvertexai-imagen、google-genai-media 的视频部分端口约定应用 HTTP 端口通常为8080uvicorn/Flask/FastAPIDev UI 固定为4000genkit start启动多语言工作流本仓库样本体系与 py/samples/README.md 保持一致——uv sync负责环境、uv run负责执行、genkit start --负责叠加观测同一套心智模型适用于目录里全部 22 个样本。按“特性命名”找样本、按上表核对凭据、复制对应命令即可在本地逐一走完 Genkit Python SDK 的核心能力面flow 的类型化与流式、generate()的统一多模型接口、工具与中间件、评估器、tracing 以及实验性 Agent。【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 