46 lines
3.5 KiB
Markdown
46 lines
3.5 KiB
Markdown
# Gemini Manifold 插件开发哲学
|
||
|
||
## 概览
|
||
|
||
- 源码位于 `plugins/pipes/gemini_mainfold/gemini_manifold.py`，作为 Open WebUI 的 Pipe 插件，主要负责把前端的请求转化成 Google Gemini/Vertex AI 的调用，并将结果通过 `AsyncGenerator` 回流给前端。
|
||
- 插件采用了 `Valves + UserValves` 的配置模式、异步事件与状态汇报、细粒度日志、文件缓存与上传中间件，以及统一响应处理器，充分体现了 Open WebUI 通用插件的开发模式。
|
||
|
||
## 核心模块
|
||
|
||
1. **`Pipe` 类（入口）**
|
||
- `pipes` 方法注册可选模型，缓存模型列表并仅在配置变更时刷新。
|
||
- `pipe` 方法为每个请求建立 Google GenAI 客户端、`EventEmitter` 与 `FilesAPIManager`，构建 `GeminiContentBuilder`，并统一把返回值交给 `_unified_response_processor`。
|
||
|
||
2. **`GeminiContentBuilder`（请求构建）**
|
||
- 解析 Open WebUI 消息、引用历史、文件上传、YouTube/Markdown 媒体等内容，并通过 `UploadStatusManager` 与 `FilesAPIManager` 协作，确保上传进度可视。
|
||
|
||
3. **`FilesAPIManager`（文件缓存+上传）**
|
||
- 采用 xxHash 内容地址、热/暖/冷路径、自定义锁、 TTL 缓存等手段防止重复上传，同时会在发生错误时用 `FilesAPIError` 抛出并告知前端。
|
||
|
||
4. **`EventEmitter` + `UploadStatusManager`（状态反馈）**
|
||
- 抽象 Toast/Status/Completion 的交互，按需异步发送，赋予前端实时反馈能力，避免阻塞主流程。
|
||
|
||
5. **统一响应处理与后置处理**
|
||
- `_unified_response_processor` 兼容流式/一次性响应，调用 `_process_part`、`_disable_special_tags` 保护前端，再在 `_do_post_processing` 发出 usage、grounding 等数据。
|
||
|
||
## 与 Open WebUI 插件哲学契合的实践
|
||
|
||
- **配置层叠与安全**：`Valves` 提供 admin 默认，`UserValves` 允许用户按需覆盖。`USER_MUST_PROVIDE_AUTH_CONFIG` + `AUTH_WHITELIST` 确保敏感场景必须使用各自凭证。
|
||
- **异步状态与进度可视**：所有上传/调用都在 `EventEmitter` 中报告 toast/status，`UploadStatusManager` 用 queue 追踪并呈现进度，流式响应直接产出 `choices` chunk 与 `[DONE]`，前端无需额外猜测。
|
||
- **功能可拓展性**：基于 `Functions.get_function_by_id` 检查 filter、依据 `features`/`toggle` 开启 Search、Code Execution、URL Context、Maps grounding，体现 Open WebUI 组件可组合的插件模型。
|
||
- **文件与资源复用**：`FilesAPIManager` 通过 deterministic name、缓存、stateless GET，提高效率；生成图片也回写到 Open WebUI 的 `Files` 模型，为前端提供可持久化的 URL。
|
||
- **透明日志与错误可控**：自定义 loguru handler（截断 `payload`）、统一的异常类、对 SDK 错误的 toast+error emission、对特殊 tag 的 ZWS 处理，确保插件运行时的状态始终可追踪并兼容前端。
|
||
- **统一流程**：全链路从 request -> builder -> client -> response processor -> post-processing，严格对齐 Open WebUI pipe+filter 结构，便于扩展和维护。
|
||
|
||
## 下一步建议
|
||
|
||
- 如果需要，可将上述内容整理到 Plugin README/开发指南中。也可以基于该文档再绘制流程图或生成寄语性文档，供团队使用。
|
||
|
||
## 进一步参考
|
||
|
||
详细的代码示例与使用场景请参见 `docs/gemini_manifold_plugin_examples.md`，包括：
|
||
|
||
- 配置层叠、异步事件、文件缓存等基础模式
|
||
- 响应处理、标签防护、异常管理等中级技巧
|
||
- 后处理流程、日志控制等高级实践
|