尧图网页设计 
AIRI 视觉模块配置指南从服务商选择、模型指定到 Vision Capture 实战【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本文以 AIRI 桌面端/网页端「设置 → 服务商 → 视觉」与「设置 → 视觉」两条配置链路为主线系统讲解如何为 AIRI 的视觉模块接入支持图像输入的模型使其理解屏幕或摄像头画面并结合仓库源码深入剖析视觉服务商与聊天服务商共用凭据的设计、模型列表加载、捕获间隔调节与推理调用链等实现细节。读完本文你将能够独立完成视觉服务商与模型的配置、启动 Vision Capture 画面捕获、完成端到端校验并掌握常见故障的排查方法。视觉模块的工作原理AIRI 的视觉模块会把捕获到的画面发送给支持图像输入的模型用于理解屏幕或摄像头画面从而为对话、角色交互提供视觉上下文。与单独维护一套视觉 API 凭据的方案不同AIRI 不为视觉模块维护独立的凭据体系它会为每个聊天服务商提供对应的视觉配置项并直接复用该服务商的字段。从源码看这一设计体现在服务商配置页中。视觉服务商页的配置 ID 由聊天服务商 ID 加上vision-前缀派生而来const sourceProviderId route.params.providerId as string const providerId vision-${sourceProviderId}该实现位于 packages/stage-pages/src/pages/settings/providers/vision/[providerId].vue。这意味着你为聊天配置的 API Key、Base URL 等字段可以直接复用为视觉配置减少重复录入。为什么视觉配置与聊天配置共用同一服务商通常同时提供聊天和图像理解模型。复用凭据可以显著减少重复配置但你仍然需要显式选择一个明确支持图像输入的模型——纯文本模型无法完成视觉任务。这是一个关键前提“视觉服务商可用”不等于“每个模型都能读图”。使用屏幕视觉前需要启动 Vision Capture仅配置视觉服务商和模型时不需要开启任何捕获工具。但如需让 AIRI 分析屏幕或窗口请前往「系统 → 开发者 → Vision Capture」授予屏幕录制权限选择要捕获的窗口或显示器点击「Start ticker」开始捕获如需将识别结果提供给 AIRI 对话再开启「Publish to character」。Vision Capture 是当前桌面端的调试开发工作流离开该页面会停止捕获循环。完整说明见 桌面端开发者工具其中明确列出了从服务商配置、屏幕授权、选择窗口、启动 ticker 到发布上下文的完整操作顺序并提示若页面一直停在权限提示需在操作系统中完成授权、完全退出并重新启动 AIRI 后再试。⚠️ 图像与凭据安全 视觉分析会把画面发送给所选服务商。不要捕获包含 API Key、密码、个人信息或未经授权内容的画面云端服务的凭据也不得提交到仓库、截图或发送给他人。第一步选择视觉服务商打开设置 → 服务商 → 视觉。选择一个你已经配置过或准备配置的聊天服务商。按该服务商卡片填写凭据。字段与其聊天服务商版本一致例如 API Key、Base URL、Azure 资源信息或 Amazon Bedrock Region。视觉服务商与聊天服务商一一对应先从侧栏「服务商 → 聊天服务商」完成对应服务商的配置再在视觉页使用相同凭据。视觉入口可用不表示每个模型都能读图仍须在模型列表中选择明确支持图像输入的模型。凭据字段的源码实现通用视觉服务商页packages/stage-pages/src/pages/settings/providers/vision/[providerId].vue展示了凭据字段的实际处理方式API Key通过ProviderApiKeyInput组件绑定providers.value[providerId]?.apiKey占位符如sk-...由服务商定义getDefinedProvider读取createProviderConfigschema 的meta.placeholderLocalized动态生成Base URL通过ProviderAdvancedSettings中的ProviderBaseUrlInput绑定baseUrl占位符默认取该服务商的defaultConfig.baseUrl校验使用useProviderValidation组合式函数完成页面下方通过ProviderValidationAlerts展示校验中、校验成功、校验失败三种状态校验失败时提供「Continue anyway」强制继续入口校验成功后可点击按钮跳转到模型选择页goToModelSelection会将当前视觉服务商写入activeProvider并路由到/settings/modules/vision。以 Amazon Bedrock 为例专门的视觉配置页packages/stage-pages/src/pages/settings/providers/vision/amazon-bedrock.vue使用固定 IDvision-amazon-bedrock除 API Key 外还包含Region字段默认值us-east-1通过ProviderAccountIdInput录入校验失败时同样提供强制继续按钮成功时可直接前往模型选择。第二步选择视觉模型打开设置 → 视觉。选择刚配置的服务商。从模型列表选择支持图片或视觉输入的模型。启用需要的视觉功能并按页面提示选择画面来源或捕获方式。如需要可以设置 Capture interval即「捕获间隔」用来调整捕获的时间间隔。模型列表的加载与选择逻辑视觉模块页packages/stage-pages/src/pages/settings/modules/vision.vue由useVisionStore驱动其核心状态定义在 packages/stage-ui/src/stores/modules/vision/store.ts持久化键名如下状态localStorage 键说明activeProvidersettings/vision/active-provider当前视觉服务商activeModelsettings/vision/active-model当前视觉模型customModelNamesettings/vision/active-custom-model手动指定的模型名不支持模型列表的服务商ollamaThinkingEnabledsettings/vision/ollama-thinking-enabledOllama 请求是否附带think参数默认 false模型选择有两个分支支持模型列表的服务商supportsModelListing为真切换服务商时自动调用loadModelsForProvider拉取模型列表见 store.ts页面用RadioCardManySelect展示支持搜索modelSearchQuery与自定义模型名输入选中后通过persistSelection写入当前 AIRI 卡片的视觉配置airiCardStore.updateActiveCardVision。不支持模型列表的服务商显示「not supported」提示并提供一个手动模型名输入框输入即时持久化。选择结果会写入settings/vision/active-provider与settings/vision/active-model视觉模块判定“已配置”的条件是configured activeProvider 且 activeModel 均非空。捕获间隔与运行状态监控同一页面下方提供Vision capture cadence面板对应原文档的 Capture intervalCapture interval通过FieldRange调节捕获间隔取值范围500ms 15000ms步长 250ms源码见 vision.vue值越小捕获越频繁、资源占用越高持久化键为settings/vision/capture-interval-ms默认值DEFAULT_CAPTURE_INTERVAL_MS 3000见 processing-store.ts。三张统计卡片分别展示 Ticker当前是否运行、上次捕获时间、Captures累计捕获次数与 Context updates累计上下文更新次数便于实时验证捕获与分析链路是否在工作。Ollama 专属开关当选中vision-ollama服务商时额外显示「Thinking (Ollama)」复选框开启时视觉请求附带think: true关闭时附带think: false。第三步配置校验使用一张不含敏感信息的测试画面。触发一次视觉分析。当 AIRI 返回画面描述或相应上下文时说明服务商、模型与画面输入已配置成功。底层推理调用链从源码看一次视觉分析最终由 packages/stage-ui/src/composables/vision/use-vision-inference.ts 的runVisionInference完成其关键步骤可概括为校验activeProvider与activeModel均已配置否则抛出Vision provider/model not configured通过providersStore.getProviderInstanceChatProvider(activeProvider)获取聊天 Provider 实例——这正是“复用聊天服务商凭据”在运行时的体现取对应的视觉工作负载提示词getVisionWorkload(input.workloadId)可用promptOverride覆盖将输入解析为 data URLparseDataUrl支持data:前缀解析 mimeType 与 base64默认image/png组装消息一条 user 消息同时包含{ type: text, text: prompt }文本部分与{ type: image_url, image_url: { url } }图像部分通过llmStore.stream(activeModel, visionProvider, messages, ...)流式推理逐段累积text-delta输出内置60 秒超时VISION_INFERENCE_TIMEOUT_MS 60_000超时通过AbortController中止请求并抛出超时错误源码注释标明该值当前为硬编码、未来应可配置。Ollama 的特殊处理也在此处当activeProvider vision-ollama时会对 Provider 的chat()方法做包装注入think: ollamaThinkingEnabled字段再交由模型推理见 use-vision-inference.ts。用 Vision Capture 实测链路推荐的端到端校验路径是先在「设置 → 服务商 → 视觉」配好服务商与模型再打开「系统 → 开发者 → Vision Capture」完成授权、选择窗口或显示器并点击「Start ticker」。该工具会捕获屏幕帧并显示提交给视觉处理流程的输出载荷用于确认视觉输入是否成功取得、帧数据是否正确以及下游视觉功能是否获得预期内容详见 桌面端开发者工具。它不是一个持久开启的全局开关——仅配置视觉服务商和模型时不需要打开此页。本地视觉模型Ollama 与 LM Studio 可作为本地视觉服务商使用配置方式与云端服务商基本一致先在本地运行一个支持图像输入的模型并确认其服务地址可被 AIRI 访问在视觉服务商页填写或保留相应 Base URL例如本地 Ollama 默认http://localhost:11434从模型列表选择该视觉模型。需要特别说明的是本地服务必须对 AIRI 可见涉及服务是否运行、Base URL 与端口是否正确、CORS 与局域网访问设置是否放行等问题。选中vision-ollama后还可通过「Thinking (Ollama)」开关控制请求是否携带think参数以满足本地推理的差异化需求。排查现象优先检查服务商无法保存与聊天版本相同的凭据字段是否完整例如 API Key、Azure 资源名称或 Bedrock Region。模型无法分析图片该模型是否明确支持图像输入切换到服务商提供的视觉模型。本地模型不可达本地服务是否运行、Base URL、端口、CORS 与局域网访问设置。请求被拒绝或额度不足服务商账户权限、模型可用地区、额度和网络连接。此外结合源码还可补充两条排查线索超时单次视觉推理内置 60 秒超时见 use-vision-inference.ts。若大图或低性能本地模型反复触发超时应优先从模型推理速度与网络链路排查。统计面板视觉模块页的 TickerCapturesContext updates 三张卡片会实时反映捕获循环是否在运行、帧是否被抓到、上下文是否被更新见 vision.vue是定位“画面没进去”类问题的最直接手段。小结AIRI 的视觉能力由“服务商复用 模型显式选择 捕获循环”三段式组成凭据与聊天服务商共用避免了重复配置模型选择区分了“能用”与“能读图”而 Vision Capture 则是把屏幕/窗口画面真正送入视觉流程的入口。按本文「选择服务商 → 选择模型 → 配置校验 → 启动捕获」的顺序操作配合模块页的捕获统计与 60 秒超时等实现细节即可快速搭建并验证一套可用的屏幕/摄像头视觉链路。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AIRI 视觉模块配置指南：从服务商选择、模型指定到 Vision Capture 实战
AIRI 视觉模块配置指南从服务商选择、模型指定到 Vision Capture 实战【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本文以 AIRI 桌面端/网页端「设置 → 服务商 → 视觉」与「设置 → 视觉」两条配置链路为主线系统讲解如何为 AIRI 的视觉模块接入支持图像输入的模型使其理解屏幕或摄像头画面并结合仓库源码深入剖析视觉服务商与聊天服务商共用凭据的设计、模型列表加载、捕获间隔调节与推理调用链等实现细节。读完本文你将能够独立完成视觉服务商与模型的配置、启动 Vision Capture 画面捕获、完成端到端校验并掌握常见故障的排查方法。视觉模块的工作原理AIRI 的视觉模块会把捕获到的画面发送给支持图像输入的模型用于理解屏幕或摄像头画面从而为对话、角色交互提供视觉上下文。与单独维护一套视觉 API 凭据的方案不同AIRI 不为视觉模块维护独立的凭据体系它会为每个聊天服务商提供对应的视觉配置项并直接复用该服务商的字段。从源码看这一设计体现在服务商配置页中。视觉服务商页的配置 ID 由聊天服务商 ID 加上vision-前缀派生而来const sourceProviderId route.params.providerId as string const providerId vision-${sourceProviderId}该实现位于 packages/stage-pages/src/pages/settings/providers/vision/[providerId].vue。这意味着你为聊天配置的 API Key、Base URL 等字段可以直接复用为视觉配置减少重复录入。为什么视觉配置与聊天配置共用同一服务商通常同时提供聊天和图像理解模型。复用凭据可以显著减少重复配置但你仍然需要显式选择一个明确支持图像输入的模型——纯文本模型无法完成视觉任务。这是一个关键前提“视觉服务商可用”不等于“每个模型都能读图”。使用屏幕视觉前需要启动 Vision Capture仅配置视觉服务商和模型时不需要开启任何捕获工具。但如需让 AIRI 分析屏幕或窗口请前往「系统 → 开发者 → Vision Capture」授予屏幕录制权限选择要捕获的窗口或显示器点击「Start ticker」开始捕获如需将识别结果提供给 AIRI 对话再开启「Publish to character」。Vision Capture 是当前桌面端的调试开发工作流离开该页面会停止捕获循环。完整说明见 桌面端开发者工具其中明确列出了从服务商配置、屏幕授权、选择窗口、启动 ticker 到发布上下文的完整操作顺序并提示若页面一直停在权限提示需在操作系统中完成授权、完全退出并重新启动 AIRI 后再试。⚠️ 图像与凭据安全 视觉分析会把画面发送给所选服务商。不要捕获包含 API Key、密码、个人信息或未经授权内容的画面云端服务的凭据也不得提交到仓库、截图或发送给他人。第一步选择视觉服务商打开设置 → 服务商 → 视觉。选择一个你已经配置过或准备配置的聊天服务商。按该服务商卡片填写凭据。字段与其聊天服务商版本一致例如 API Key、Base URL、Azure 资源信息或 Amazon Bedrock Region。视觉服务商与聊天服务商一一对应先从侧栏「服务商 → 聊天服务商」完成对应服务商的配置再在视觉页使用相同凭据。视觉入口可用不表示每个模型都能读图仍须在模型列表中选择明确支持图像输入的模型。凭据字段的源码实现通用视觉服务商页packages/stage-pages/src/pages/settings/providers/vision/[providerId].vue展示了凭据字段的实际处理方式API Key通过ProviderApiKeyInput组件绑定providers.value[providerId]?.apiKey占位符如sk-...由服务商定义getDefinedProvider读取createProviderConfigschema 的meta.placeholderLocalized动态生成Base URL通过ProviderAdvancedSettings中的ProviderBaseUrlInput绑定baseUrl占位符默认取该服务商的defaultConfig.baseUrl校验使用useProviderValidation组合式函数完成页面下方通过ProviderValidationAlerts展示校验中、校验成功、校验失败三种状态校验失败时提供「Continue anyway」强制继续入口校验成功后可点击按钮跳转到模型选择页goToModelSelection会将当前视觉服务商写入activeProvider并路由到/settings/modules/vision。以 Amazon Bedrock 为例专门的视觉配置页packages/stage-pages/src/pages/settings/providers/vision/amazon-bedrock.vue使用固定 IDvision-amazon-bedrock除 API Key 外还包含Region字段默认值us-east-1通过ProviderAccountIdInput录入校验失败时同样提供强制继续按钮成功时可直接前往模型选择。第二步选择视觉模型打开设置 → 视觉。选择刚配置的服务商。从模型列表选择支持图片或视觉输入的模型。启用需要的视觉功能并按页面提示选择画面来源或捕获方式。如需要可以设置 Capture interval即「捕获间隔」用来调整捕获的时间间隔。模型列表的加载与选择逻辑视觉模块页packages/stage-pages/src/pages/settings/modules/vision.vue由useVisionStore驱动其核心状态定义在 packages/stage-ui/src/stores/modules/vision/store.ts持久化键名如下状态localStorage 键说明activeProvidersettings/vision/active-provider当前视觉服务商activeModelsettings/vision/active-model当前视觉模型customModelNamesettings/vision/active-custom-model手动指定的模型名不支持模型列表的服务商ollamaThinkingEnabledsettings/vision/ollama-thinking-enabledOllama 请求是否附带think参数默认 false模型选择有两个分支支持模型列表的服务商supportsModelListing为真切换服务商时自动调用loadModelsForProvider拉取模型列表见 store.ts页面用RadioCardManySelect展示支持搜索modelSearchQuery与自定义模型名输入选中后通过persistSelection写入当前 AIRI 卡片的视觉配置airiCardStore.updateActiveCardVision。不支持模型列表的服务商显示「not supported」提示并提供一个手动模型名输入框输入即时持久化。选择结果会写入settings/vision/active-provider与settings/vision/active-model视觉模块判定“已配置”的条件是configured activeProvider 且 activeModel 均非空。捕获间隔与运行状态监控同一页面下方提供Vision capture cadence面板对应原文档的 Capture intervalCapture interval通过FieldRange调节捕获间隔取值范围500ms 15000ms步长 250ms源码见 vision.vue值越小捕获越频繁、资源占用越高持久化键为settings/vision/capture-interval-ms默认值DEFAULT_CAPTURE_INTERVAL_MS 3000见 processing-store.ts。三张统计卡片分别展示 Ticker当前是否运行、上次捕获时间、Captures累计捕获次数与 Context updates累计上下文更新次数便于实时验证捕获与分析链路是否在工作。Ollama 专属开关当选中vision-ollama服务商时额外显示「Thinking (Ollama)」复选框开启时视觉请求附带think: true关闭时附带think: false。第三步配置校验使用一张不含敏感信息的测试画面。触发一次视觉分析。当 AIRI 返回画面描述或相应上下文时说明服务商、模型与画面输入已配置成功。底层推理调用链从源码看一次视觉分析最终由 packages/stage-ui/src/composables/vision/use-vision-inference.ts 的runVisionInference完成其关键步骤可概括为校验activeProvider与activeModel均已配置否则抛出Vision provider/model not configured通过providersStore.getProviderInstanceChatProvider(activeProvider)获取聊天 Provider 实例——这正是“复用聊天服务商凭据”在运行时的体现取对应的视觉工作负载提示词getVisionWorkload(input.workloadId)可用promptOverride覆盖将输入解析为 data URLparseDataUrl支持data:前缀解析 mimeType 与 base64默认image/png组装消息一条 user 消息同时包含{ type: text, text: prompt }文本部分与{ type: image_url, image_url: { url } }图像部分通过llmStore.stream(activeModel, visionProvider, messages, ...)流式推理逐段累积text-delta输出内置60 秒超时VISION_INFERENCE_TIMEOUT_MS 60_000超时通过AbortController中止请求并抛出超时错误源码注释标明该值当前为硬编码、未来应可配置。Ollama 的特殊处理也在此处当activeProvider vision-ollama时会对 Provider 的chat()方法做包装注入think: ollamaThinkingEnabled字段再交由模型推理见 use-vision-inference.ts。用 Vision Capture 实测链路推荐的端到端校验路径是先在「设置 → 服务商 → 视觉」配好服务商与模型再打开「系统 → 开发者 → Vision Capture」完成授权、选择窗口或显示器并点击「Start ticker」。该工具会捕获屏幕帧并显示提交给视觉处理流程的输出载荷用于确认视觉输入是否成功取得、帧数据是否正确以及下游视觉功能是否获得预期内容详见 桌面端开发者工具。它不是一个持久开启的全局开关——仅配置视觉服务商和模型时不需要打开此页。本地视觉模型Ollama 与 LM Studio 可作为本地视觉服务商使用配置方式与云端服务商基本一致先在本地运行一个支持图像输入的模型并确认其服务地址可被 AIRI 访问在视觉服务商页填写或保留相应 Base URL例如本地 Ollama 默认http://localhost:11434从模型列表选择该视觉模型。需要特别说明的是本地服务必须对 AIRI 可见涉及服务是否运行、Base URL 与端口是否正确、CORS 与局域网访问设置是否放行等问题。选中vision-ollama后还可通过「Thinking (Ollama)」开关控制请求是否携带think参数以满足本地推理的差异化需求。排查现象优先检查服务商无法保存与聊天版本相同的凭据字段是否完整例如 API Key、Azure 资源名称或 Bedrock Region。模型无法分析图片该模型是否明确支持图像输入切换到服务商提供的视觉模型。本地模型不可达本地服务是否运行、Base URL、端口、CORS 与局域网访问设置。请求被拒绝或额度不足服务商账户权限、模型可用地区、额度和网络连接。此外结合源码还可补充两条排查线索超时单次视觉推理内置 60 秒超时见 use-vision-inference.ts。若大图或低性能本地模型反复触发超时应优先从模型推理速度与网络链路排查。统计面板视觉模块页的 TickerCapturesContext updates 三张卡片会实时反映捕获循环是否在运行、帧是否被抓到、上下文是否被更新见 vision.vue是定位“画面没进去”类问题的最直接手段。小结AIRI 的视觉能力由“服务商复用 模型显式选择 捕获循环”三段式组成凭据与聊天服务商共用避免了重复配置模型选择区分了“能用”与“能读图”而 Vision Capture 则是把屏幕/窗口画面真正送入视觉流程的入口。按本文「选择服务商 → 选择模型 → 配置校验 → 启动捕获」的顺序操作配合模块页的捕获统计与 60 秒超时等实现细节即可快速搭建并验证一套可用的屏幕/摄像头视觉链路。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考