Genkit Ollama 插件全解析从 CHANGELOG 看本地大模型接入的实现细节【免费下载链接】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本文以genkit-ollama插件的 CHANGELOG 为骨架逐一拆解其中新增、变更与修复的每一项能力OllamaConfig采样参数、视觉模型media支持、可调用的request_headers、超时传播、连接错误处理与工具 schema 推断并结合仓库源码models.py、plugin_api.py、embedders.py与测试用例plugin_api_test.py说明其底层实现原理。读完本文你将完整掌握在 GenkitPython中把 Ollama 本地模型接入聊天、流式生成、工具调用、多模态与向量嵌入的配置方法与排查手段。一、CHANGELOG 说了什么一次转正带来的能力跃迁genkit-ollama的 CHANGELOG 采用 Keep a Changelog 格式并遵循语义化版本其 [Unreleased] 条目集中记录了一次关键升级插件从社区状态转正为一等公民first-party同时带来了配置、错误处理与元数据层面的一批实质改进。逐条翻译过来本次变更涵盖六个方向新增OllamaConfig采样参数、OllamaSupports.media视觉开关、可调用请求头、超时传播、OllamaConnectionError、EmbeddingDefinition根导出、可运行示例变更插件元数据按 API 类型声明能力、request_headers真正生效、工具输入 schema 推断修复top_p参数映射错误。本文后续各节将按配置参数 → 能力声明 → 网络与错误处理 → 导出与示例 → 行为修复的顺序把每一条都讲透。二、OllamaConfig六个 Ollama 专属采样旋钮2.1 字段速览OllamaConfig继承 Genkit 公共的ModelConfig并追加六个 Ollama 专属字段声明位置在 models.py字段类型含义落点thinkbool \| low \| medium \| high \| None推理模型思维链开关/强度chat/generate 的顶层请求参数keep_alivefloat \| str \| None模型在内存中的驻留时长顶层请求参数num_ctxint \| None上下文窗口大小token 数采样optionsmin_pfloat \| None最小概率阈值过滤低置信 token采样optionsseedint \| None随机种子可复现输出采样optionsnum_predictint \| None最多生成的 token 数采样options2.2 参数如何分流options与顶层 kwargs 的两条路径源码注释明确指出think与keep_alive是 Ollamachat/generate调用的顶层请求参数而不是采样选项options放在options内会被服务端拒绝。因此 models.py 中的两个静态方法分工明确build_request_options(config)归一化配置为 snake_case 的采样选项字典。其中 Genkit 的max_output_tokens会映射为 Ollama 的num_predict显式给出的num_predict优先stop_sequences映射为stopversion/api_key这类 Genkit 记账字段被剔除OllamaConfig的extra键例如repeatPenalty也会以 snake_case 原样透传保证新采样参数无需升级 SDK 即可到达服务端。build_request_kwargs(config)只提取think与keep_alive作为顶层 kwargs 返回。一个典型用法来自 README.mdfrom genkit_ollama import OllamaConfig # 推理模型 32k 上下文窗口模型常驻内存 1 小时 response await ai.generate( modelollama/deepseek-r1, promptPlan a small REST API., configOllamaConfig( thinkTrue, num_ctx32_000, keep_alive1h, temperature0.2, ), )2.3think参数的两层语义think支持布尔值或low/medium/high强度字符串。在响应组装阶段models.py 的_build_multimodal_chat_response/_build_generate_response会优先读取 Ollama 响应中的message.thinking或generate响应的thinking字段将其包装为前置的ReasoningPart从而让 Dev UI 把思维链与最终答案分开渲染当模型没有独立的thinking字段、而是把思维链内联在think.../think标签中时只要请求显式开启了think_thinking_requested判定插件会用_parse_thinking正则(?is)(?:think|thinking)(.*?)/(?:think|thinking)与 Go 插件的thinkingRegex对齐把思维链剥离出来。该兜底仅作用于完整非流式响应避免标签在流式分片中被打断而误判。三、OllamaSupports.media视觉模型的选入式能力声明OllamaSupports定义于 models.py默认值为toolsTrue, mediaFalseclass OllamaSupports(BaseModel): tools: bool True media: bool Falsemedia默认关闭是刻意设计媒体能力按模型逐个选入opt-in避免向 Dev UI 虚假声明底层模型并不具备的能力。启用方式如下README.mdfrom genkit_ollama import ModelDefinition, Ollama, OllamaSupports Ollama(models[ModelDefinition(namellava, supportsOllamaSupports(mediaTrue))])需要说明的是ModelDefinition默认api_typeOllamaAPITypes.CHAT见 models.py 与 constants.py 中CHAT/GENERATE两个枚举值。与之相关的多媒体实现细节是Ollama Python 客户端的Image类型只接受 base64 字符串、原始字节或本地文件路径不接受 HTTP URL 或完整 data URI。因此 models.py 的_resolve_image会分三种情况预处理MediaPart.urldata URIdata:image/jpeg;base64,...剥掉前缀返回裸 base64 字符串HTTP/HTTPS URL用共享的get_cached_client下载为原始字节并附带User-Agent: Genkit/1.0 (...)请求头规避 Wikipedia 等站点对无 UA 请求的 403 拦截本地路径 / 裸 base64原样透传给Image。这也是 Python 插件与 JS 插件唯一的行为分叉JS 侧由 Ollama 服务端原生处理 URL 抓取而 Python 侧必须客户端显式下载。四、request_headers从存而不用到按请求解析CHANGELOG 明确记录了两点request_headers现在接受同步或异步可调用对象且被真正传播到ollama.AsyncClient此前是存了但从未发送。类型定义在 plugin_api.pydataclass(frozenTrue) class RequestHeaderParams: server_address: str model: ModelDefinition | EmbeddingDefinition | None None model_request: ModelRequest | None None embed_request: EmbedRequest | None None RequestHeaderFunction Callable[ [RequestHeaderParams], dict[str, str] | None | Awaitable[dict[str, str] | None], ] RequestHeaders dict[str, str] | RequestHeaderFunctionRequestHeaderParams与 JS 插件的RequestHeaderFunction参数对齐回调可以拿到服务器地址、目标模型/嵌入器定义以及完整请求对象从而签发每个请求专用的短时 token。# 静态头一次应用到缓存的客户端 Ollama(request_headers{Authorization: Bearer token}) # 异步解析头每次请求重新求值短时 token 自动续期 from genkit_ollama import RequestHeaderParams async def auth_headers(params: RequestHeaderParams) - dict[str, str]: return {Authorization: fBearer {await mint_token(params.server_address)}} Ollama(request_headersauth_headers, timeout60.0)底层机制plugin_api.py值得展开静态 dict直接烤进按事件循环缓存的共享客户端loop_local_client跨请求复用、常开不关闭可调用对象_client_for_request每次请求都调用一次inspect.isawaitable支持同步与异步两种形态因为 Ollama SDK 在构造时就把 header 烤进客户端、没有按请求注入 header 的钩子所以每次都要新建一个临时客户端并在退出时关闭其内部 httpx 连接池通过_client.aclose()幂等防止长驻进程累积连接池。plugin_api_test.py 中的test_sync_callable_headers_resolved_per_request、test_async_callable_headers_resolved_per_request、test_model_action_passes_request_context_to_header_callable与test_embedder_action_passes_request_context_to_header_callable分别验证了可调用头在init()时不会被急切求值、每次请求重新解析、模型/嵌入器请求上下文正确传递、以及每次请求的连接池确实被关闭。五、timeout直达底层 httpx 客户端timeout构造参数会原样转发给ollama.AsyncClient其内部即 httpx实现位于 plugin_api.pykwargs {host: self.server_address, headers: ...} if self.timeout is not None: kwargs[timeout] self.timeout return ollama_api.AsyncClient(**kwargs)注意None时完全省略该参数使用 SDK 默认值只有显式给出数值秒才透传。测试test_make_client_forwards_host_headers_and_timeout与test_make_client_omits_timeout_when_noneplugin_api_test.py分别锁定了这两种行为。六、OllamaConnectionError让连不上变成可操作提示新增的OllamaConnectionErrorerrors.py 中定义继承内建ConnectionError由wrap_connection_errors(server_address)上下文管理器统一产生覆盖两类失败Ollama SDK 把httpx.ConnectError转成内建ConnectionError再抛出的情况SDK 未拦截的超时httpx.ReadTimeout/PoolTimeout等httpx.TransportError。真正的服务端 HTTP 状态错误SDK 转成ollama.ResponseError或裸HTTPStatusError不会被误包装。错误消息会带上尝试连接的地址例如Cannot reach the Ollama server at http://127.0.0.1:11434. Start it with ollama serve (or set server_address to a reachable host).超时则有独立的timed out文案。一个值得注意的边界图片 URL 的抓取发生在wrap_connection_errors之外models.py因此图片宿主不可达不会被打扮成Ollama 服务器宕机测试test_model_action_does_not_wrap_media_fetch_error专门验证了这一点。排查建议先确认ollama serve是否在运行再确认server_address指向可达主机默认地址为http://127.0.0.1:11434constants.py。七、EmbeddingDefinition根导出与嵌入能力CHANGELOG 提到EmbeddingDefinition现在可以从包根genkit_ollama直接导入此前只能从genkit_ollama.embedders子模块导入。查看init.py包根现在统一导出EmbeddingDefinition、ModelDefinition、Ollama、OllamaConfig、OllamaConnectionError、OllamaSupports、RequestHeaderFunction、RequestHeaderParams、RequestHeaders、ollama_name与package_name。EmbeddingDefinitionembedders.py包含name与可选的dimensions用于信息展示或未来截断支持。嵌入流程由OllamaEmbedder.embed实现把 Genkit 的EmbedRequest文档内容展平为字符串列表调用client.embed(model..., input...)再包装为EmbedResponse。基础用法from genkit import Genkit from genkit_ollama import EmbeddingDefinition, ModelDefinition, Ollama ai Genkit( plugins[ Ollama( models[ModelDefinition(namellama3.2)], embedders[EmbeddingDefinition(namenomic-embed-text)], ) ], modelollama/llama3.2, ) embeddings await ai.embed(embedderollama/nomic-embed-text, contentlocal inference) print(len(embeddings[0].embedding))八、可运行示例chat / 流式 / 工具调用 / 嵌入一网打尽CHANGELOG 记录了示例程序位于py/samples/ollama-sample/覆盖聊天、流式、工具调用与嵌入四种场景配合ai.run_main(...)作为完整入口注意 README 提醒await必须放在async def中模块顶层直接写会抛SyntaxError。完整可复现的安装与启动步骤如下见 README.md# 1. 安装依赖 uv add genkit genkit-ollama # 2. 启动本地 Ollama 服务默认 http://127.0.0.1:11434 ollama serve # 3. 提前拉取要用到的模型 ollama pull llama3.2 ollama pull nomic-embed-text流式生成与工具调用的代码形态# 流式 stream_response ai.generate_stream(promptStream a haiku about Ollama.) async for chunk in stream_response.stream: print(chunk.text, end, flushTrue) final await stream_response.response # 工具调用Ollama 工具输入必须是 object schema基本类型请用 Pydantic 包一层 from pydantic import BaseModel, Field class WeatherInput(BaseModel): city: str Field(descriptionCity to look up) ai.tool() async def current_weather(input: WeatherInput) - str: return f{input.city} is 18°C and partly cloudy. response await ai.generate(promptWhat is the weather in London?, tools[current_weather])Schema 约束输出JSON同样开箱即用from pydantic import BaseModel class Haiku(BaseModel): line_one: str line_two: str line_three: str response await ai.generate(promptWrite a haiku about local models., output_schemaHaiku) print(response.output)九、元数据修正按 API 类型声明能力CHANGELOG 指出插件元数据改为反映每种 API 类型的能力generateAPI 不再声明multiturn/tools。这由ollama_model_infoplugin_api.py实现——只有CHAT类型模型才声明multiturn、tools而media还需supports.mediaTrue双重门控。测试锁定了三种形态plugin_api_test.pyCHAT media 模型multiturn/tools/media全为TrueGENERATE 模型三者全为FalsesystemRole仍为True动态解析未预配置的模型广告完整泛用能力集toolsTrue, mediaTrue与 JS 的GENERIC_MODEL_INFO、Go 的defaultOllamaSupports对齐——因为动态发现的模型无法做能力探测。十、两处行为修复top_p与工具 schema 推断10.1top_p映射修复此前ModelConfig中的top_p会被原样发送为topP驼峰而被 Ollama 忽略现在build_request_options统一把配置键做to_snake归一化models.pytopP正确落为top_p进入ollama.Options并先经Options模型做类型强制Genkit 把top_k等类型为 float而 Ollama 需要 int再把Options未收录的新参数如min_p合并回去保证新旧采样参数都能到达服务端。10.2 工具输入 schema 推断_convert_parametersmodels.py规定Ollama 只支持 object 类型的工具输入与 JS 的isValidOllamaTool对齐非 object 直接抛ValueError。此前声明了properties却省略type的 schema 会被丢弃现在会推断为 object schema属性类型解析_property_type还兼容Optional[str]这类anyOf/oneOf联合 schema把它们映射为 OllamaProperty.type接受的列表形式避免required指向不存在的属性。README 中用 Pydantic 包一层基本类型的建议正是对这一约束的呼应。十一、小结从变更日志到可用插件回到 CHANGELOG 本身pyproject.toml 显示当前包版本为0.11.0Beta 阶段支持 Python 3.10–3.14依赖genkit、ollama0.5.3,1.0与structlog25.2.0。把 CHANGELOG 的每一条改动与源码、测试对照后可以看到这次转正的实质是一次完整的工程化收口配置参数从能传到传得对snake_case 归一化与顶层 kwargs 分流、能力声明从拍脑袋到按 API 类型如实上报、网络行为从存而不用到按请求解析 连接池管理、错误从晦涩的传输异常到带地址与修复提示的OllamaConnectionError。对于需要在本地硬件上运行 LLM、追求数据不出机器的开发者而言这份插件已经覆盖了从单轮问答、流式输出、工具调用、视觉输入到向量嵌入的完整使用链路。【免费下载链接】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），仅供参考