Page Assist 接入 Gemini Enterprise Agent PlatformVertex AI零代理、浏览器内直连认证与模型配置全指南【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist本篇技术指南围绕 Page Assist 对 Google Cloud Gemini Enterprise Agent Platform原名 Vertex AI的原生接入能力展开讲解从 Google Cloud 前置条件准备、扩展内可视化配置到浏览器内 JWT 签名换取短时 access token 的认证原理与常见故障排查的完整链路。读完本文你将掌握如何在不部署任何本地代理如 LiteLLM的前提下让 Page Assist 直接以服务账号身份调用 GCP 项目中的 Gemini 模型并能在 401/403/404 报错时快速定位原因。::: info 命名说明 在 Google Cloud Next 2026 上Vertex AI 被更名为 Gemini Enterprise Agent Platform。API 端点、模型 ID 与认证方式完全不变仅产品名称不同。本文沿用文档与扩展内一致的 Vertex AI 称谓便于检索定位。 :::一、与 Google AI 提供方的区别两种接入方式的适用边界Page Assist 同时内置了 Google 系两个提供方理解其差异是选型的第一步Google AIGoogle AI Studio在 providers 清单 中以gemini为标识baseUrl指向https://generativelanguage.googleapis.com/v1beta/openai使用简单的 API Key 即可完成认证对应扩展内 ChatGoogleAI 客户端分支。Gemini Enterprise Agent PlatformVertex AI在 providers 清单 中以vertex为标识baseUrl为空字符串——因为它需要根据「项目 ID Region」动态构建。当你的 Gemini 访问权限位于 Google Cloud 项目内计费、配额、IAM 均由 Google Cloud 管理时应选择此提供方。二、前置条件三样东西缺一不可开始配置前请确认以下三件事已就绪启用 Vertex AI API 的 Google Cloud 项目在 Google Cloud Console 中进入APIs Services → Enable APIs and Services启用Vertex AI API。具备 Vertex AI 调用权限的服务账号为其授予Vertex AI Userroles/aiplatform.user角色即可满足调用需求。JSON 格式的服务账号密钥文件通过IAM Admin → Service Accounts → 选择账号 → Keys → Add key → Create new key → JSON下载。该.json文件内容形如{ type: service_account, project_id: my-gcp-project-123456, private_key_id: ..., private_key: -----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n, client_email: page-assistmy-gcp-project-123456.iam.gserviceaccount.com, ...: ... }从源码角度验证vertex-auth.ts 定义的服务账号类型ServiceAccount实际只需client_email与private_key两个必填字段project_id与token_uri为可选——这决定了后续认证逻辑的分支走向。三、扩展内配置从添加提供方到选择模型点击浏览器工具栏上的 Page Assist 图标。点击Settings图标进入设置页。切换到OpenAI Compatible API标签页。点击Add Provider按钮。在下拉列表中选择Gemini Enterprise Agent Platform (Vertex AI)。填写表单字段说明Provider Name任意便于识别的标签例如Vertex AI。Google Cloud Project ID你的 GCP 项目 ID例如my-gcp-project-123456。Location / Region模型所在区域例如us-central1选择global则使用全局端点。Service Account JSON粘贴服务账号.json密钥文件的完整内容。点击Save按钮保存。Page Assist 会打开模型列表勾选需要的 Gemini 模型后保存即可。3.1 表单背后发生了什么自动填充与 Base URL 构建设置表单的实现openai.tsx揭示了两个值得注意的细节Project ID 自动填充当你粘贴服务账号 JSON 后表单会解析其中的project_id字段并自动填入 Project ID 输入框openai.tsx并给出上传成功的提示——因此即使你记不清项目 ID也不会填错。Base URL 动态生成保存时不会使用预置的固定地址而是调用buildVertexBaseUrl(projectId, location)openai.tsx现场拼接端点并将vertexProjectId、vertexLocation连同 API Key 一起持久化到 IndexedDB字段定义见 dexie/types.ts 与 dexie/openai.ts。具体的拼接规则在 vertex-auth.ts 中区域端点https://{loc}-aiplatform.googleapis.com/v1beta1/projects/{p}/locations/{loc}/endpoints/openapi全局端点https://aiplatform.googleapis.com/v1beta1/projects/{p}/locations/global/endpoints/openapi其中{loc}会按区域名拼入主机名如us-central1-aiplatform.googleapis.comglobal则使用不带区域前缀的域名。四、模型选择内置清单、google/前缀与自定义模型添加提供方后可从可用 Gemini 模型中选择例如gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-lite、gemini-3.5-flash若需要特定模型 ID也可通过Manage Models → Add Custom Model手动添加。4.1 为什么模型列表是「内置清单」而非动态拉取大多数 OpenAI 兼容端点通过GET /models动态返回模型列表但 Vertex AI 的 OpenAI 兼容端点并不提供可靠的/models列表。因此 Page Assist 在检测到目标是 Vertex AI 端点时通过isVertexAI()判断主机名是否以aiplatform.googleapis.com结尾见 vertex-auth.ts直接走 getVertexModels() 返回一份精心维护的已知模型清单该分支在 openai.ts 中被调用。当前内置的 chat 模型清单包含gemini-3-pro-preview、gemini-3.1-pro-previewPro 档gemini-3.5-flash、gemini-3-flash-preview、gemini-3.1-flash-liteFlash 档gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-litegemini-flash-latest、gemini-flash-lite-latest同时为 embedding 场景提供了gemini-embedding-2、gemini-embedding-001、text-embedding-005、text-multilingual-embedding-002等向量模型。4.2 必须了解google/发布方前缀Vertex AI 的 OpenAI 兼容面使用google/发布方前缀作为模型 ID 的一部分例如google/gemini-2.5-flash。当你从模型列表中选择模型时Page Assist 已替你处理好该前缀但使用Add Custom Model手动输入模型 ID 时需自行确认 ID 的准确性是否需要前缀取决于你的实际调用方式。::: warning 模型可用性因项目与区域而异 并非所有 Gemini 模型在每个项目、每个区域都可用。尤其是一些较新的 pro 档模型如gemini-3-pro-preview处于gated preview受限预览状态即使模型存在在项目被加入白名单前也会返回404NOT_FOUND——your project does not have access。这是 Google 侧的访问闸门并非 Page Assist 的问题。如需申请访问权限在 Google Cloud Console 的Vertex AI Model Garden中找到该模型使用其中的Enable / Request access功能授权通过后通过Manage Models → Add Custom Model手动添加输入如gemini-3-pro-preview的 ID即可。若模型返回 404可尝试换用其他模型、切换到其他区域或global、或在 Model Garden 中确认访问权限。Gemini 3 的flash档gemini-3.5-flash、gemini-3-flash-preview、gemini-3.1-flash-lite通常无需特殊授权即可使用。 :::五、认证原理纯浏览器内的 JWT → OAuth2 Token 交换Vertex AI 不像 Google AI Studio 那样接受简单 API Key它要求短时的 OAuth2 access token。Page Assist 的目标是全程纯浏览器运行、无需任何本地代理因此实现了完整的「服务账号 JSON → JWT 签名 → 换取 access token」链路核心代码集中在 vertex-auth.ts。5.1 数据边界服务账号 JSON 只本地存储在扩展中除 Google 官方令牌端点oauth2.googleapis.comscope 为https://www.googleapis.com/auth/cloud-platform见 vertex-auth.ts外不会发送到任何其他地址。所有请求直接发往区域化 Vertex AI 端点https://{LOCATION}-aiplatform.googleapis.com/.../endpoints/openapi选择global时使用全局端点。5.2 令牌铸造的完整步骤解析凭据parseServiceAccount()vertex-auth.ts尝试将输入解析为服务账号 JSON若缺少private_key或client_email则判定为「不是服务账号」此时原始字符串被直接当作 access token 使用。构造并签名 JWT使用浏览器 Web Crypto API 的crypto.subtle.importKey/sign以RS256RSASSA-PKCS1-v1_5 SHA-256对{iss, scope, aud, iat, exp}声明签名。JWT 的exp设为当前时间 3600 秒aud指向令牌端点vertex-auth.ts。换取 access token以grant_typeurn:ietf:params:oauth:grant-type:jwt-bearer向令牌端点发起表单请求获得access_tokenvertex-auth.ts。缓存与自动刷新铸得的 token 按client_email缓存在内存Map中vertex-auth.ts并在到期前 60 秒就提前刷新vertex-auth.ts避免临近过期时的竞态。因此日常对话不会对每一次请求都重新签名 JWT。注入模型客户端在 models/index.ts 的vertex分支中getGoogleCloudAccessToken()返回的 token 被作为openAIApiKey与configuration.apiKey传入CustomChatOpenAI从而以 OpenAI 兼容协议直连 Vertex 端点。5.3 快速替代方案直接粘贴原始 access token如果你不想配置服务账号 JSON也可以把原始 access token例如通过gcloud auth print-access-token获取直接粘贴进 Service Account JSON 字段。此时parseServiceAccount()解析失败原始 token 会被原样使用。注意这类 token 大约一小时后过期需要手动更换——因此日常使用仍推荐服务账号 JSON它才能实现自动刷新。六、故障排查401 / 403 / 404 定位指南错误可能原因与处理401 /UNAUTHENTICATEDJSON 未完整粘贴服务账号缺少Vertex AI User角色若粘贴的是原始 access token可能已过期。403 /PERMISSION_DENIED项目未启用 Vertex AI API或服务账号权限不足回到前置条件第 1、2 步检查。404 / model not found确认模型在所选区域可用且模型 ID 正确。部分模型仅限特定区域global覆盖范围最广。另注意 gated preview 模型需在 Model Garden 申请白名单见 4.2 节。七、核心参考文件索引Vertex AI 接入文档本文的原始依据含官方配置步骤与故障排查。认证与工具函数JWT 签名、token 缓存刷新、Base URL 构建、内置模型清单。OpenAI 兼容模型拉取Vertex AI 分支如何返回内置模型清单。模型客户端装配vertex提供方如何注入 access token 构造CustomChatOpenAI。提供方清单vertex提供方的标签与空 Base URL 设计。配置表单实现Project ID 自动填充、Base URL 动态构建与字段校验。配置持久化vertexProjectId/vertexLocation字段定义。按照上述流程完成配置后Page Assist 即可在浏览器内直接、安全地调用你 GCP 项目中的 Gemini 模型用于侧边栏对话、网页问答、知识库检索等场景——全程不依赖任何中转代理。【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Page Assist 接入 Gemini Enterprise Agent Platform（Vertex AI）：零代理、浏览器内直连认证与模型配置全指南
Page Assist 接入 Gemini Enterprise Agent PlatformVertex AI零代理、浏览器内直连认证与模型配置全指南【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist本篇技术指南围绕 Page Assist 对 Google Cloud Gemini Enterprise Agent Platform原名 Vertex AI的原生接入能力展开讲解从 Google Cloud 前置条件准备、扩展内可视化配置到浏览器内 JWT 签名换取短时 access token 的认证原理与常见故障排查的完整链路。读完本文你将掌握如何在不部署任何本地代理如 LiteLLM的前提下让 Page Assist 直接以服务账号身份调用 GCP 项目中的 Gemini 模型并能在 401/403/404 报错时快速定位原因。::: info 命名说明 在 Google Cloud Next 2026 上Vertex AI 被更名为 Gemini Enterprise Agent Platform。API 端点、模型 ID 与认证方式完全不变仅产品名称不同。本文沿用文档与扩展内一致的 Vertex AI 称谓便于检索定位。 :::一、与 Google AI 提供方的区别两种接入方式的适用边界Page Assist 同时内置了 Google 系两个提供方理解其差异是选型的第一步Google AIGoogle AI Studio在 providers 清单 中以gemini为标识baseUrl指向https://generativelanguage.googleapis.com/v1beta/openai使用简单的 API Key 即可完成认证对应扩展内 ChatGoogleAI 客户端分支。Gemini Enterprise Agent PlatformVertex AI在 providers 清单 中以vertex为标识baseUrl为空字符串——因为它需要根据「项目 ID Region」动态构建。当你的 Gemini 访问权限位于 Google Cloud 项目内计费、配额、IAM 均由 Google Cloud 管理时应选择此提供方。二、前置条件三样东西缺一不可开始配置前请确认以下三件事已就绪启用 Vertex AI API 的 Google Cloud 项目在 Google Cloud Console 中进入APIs Services → Enable APIs and Services启用Vertex AI API。具备 Vertex AI 调用权限的服务账号为其授予Vertex AI Userroles/aiplatform.user角色即可满足调用需求。JSON 格式的服务账号密钥文件通过IAM Admin → Service Accounts → 选择账号 → Keys → Add key → Create new key → JSON下载。该.json文件内容形如{ type: service_account, project_id: my-gcp-project-123456, private_key_id: ..., private_key: -----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n, client_email: page-assistmy-gcp-project-123456.iam.gserviceaccount.com, ...: ... }从源码角度验证vertex-auth.ts 定义的服务账号类型ServiceAccount实际只需client_email与private_key两个必填字段project_id与token_uri为可选——这决定了后续认证逻辑的分支走向。三、扩展内配置从添加提供方到选择模型点击浏览器工具栏上的 Page Assist 图标。点击Settings图标进入设置页。切换到OpenAI Compatible API标签页。点击Add Provider按钮。在下拉列表中选择Gemini Enterprise Agent Platform (Vertex AI)。填写表单字段说明Provider Name任意便于识别的标签例如Vertex AI。Google Cloud Project ID你的 GCP 项目 ID例如my-gcp-project-123456。Location / Region模型所在区域例如us-central1选择global则使用全局端点。Service Account JSON粘贴服务账号.json密钥文件的完整内容。点击Save按钮保存。Page Assist 会打开模型列表勾选需要的 Gemini 模型后保存即可。3.1 表单背后发生了什么自动填充与 Base URL 构建设置表单的实现openai.tsx揭示了两个值得注意的细节Project ID 自动填充当你粘贴服务账号 JSON 后表单会解析其中的project_id字段并自动填入 Project ID 输入框openai.tsx并给出上传成功的提示——因此即使你记不清项目 ID也不会填错。Base URL 动态生成保存时不会使用预置的固定地址而是调用buildVertexBaseUrl(projectId, location)openai.tsx现场拼接端点并将vertexProjectId、vertexLocation连同 API Key 一起持久化到 IndexedDB字段定义见 dexie/types.ts 与 dexie/openai.ts。具体的拼接规则在 vertex-auth.ts 中区域端点https://{loc}-aiplatform.googleapis.com/v1beta1/projects/{p}/locations/{loc}/endpoints/openapi全局端点https://aiplatform.googleapis.com/v1beta1/projects/{p}/locations/global/endpoints/openapi其中{loc}会按区域名拼入主机名如us-central1-aiplatform.googleapis.comglobal则使用不带区域前缀的域名。四、模型选择内置清单、google/前缀与自定义模型添加提供方后可从可用 Gemini 模型中选择例如gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-lite、gemini-3.5-flash若需要特定模型 ID也可通过Manage Models → Add Custom Model手动添加。4.1 为什么模型列表是「内置清单」而非动态拉取大多数 OpenAI 兼容端点通过GET /models动态返回模型列表但 Vertex AI 的 OpenAI 兼容端点并不提供可靠的/models列表。因此 Page Assist 在检测到目标是 Vertex AI 端点时通过isVertexAI()判断主机名是否以aiplatform.googleapis.com结尾见 vertex-auth.ts直接走 getVertexModels() 返回一份精心维护的已知模型清单该分支在 openai.ts 中被调用。当前内置的 chat 模型清单包含gemini-3-pro-preview、gemini-3.1-pro-previewPro 档gemini-3.5-flash、gemini-3-flash-preview、gemini-3.1-flash-liteFlash 档gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-litegemini-flash-latest、gemini-flash-lite-latest同时为 embedding 场景提供了gemini-embedding-2、gemini-embedding-001、text-embedding-005、text-multilingual-embedding-002等向量模型。4.2 必须了解google/发布方前缀Vertex AI 的 OpenAI 兼容面使用google/发布方前缀作为模型 ID 的一部分例如google/gemini-2.5-flash。当你从模型列表中选择模型时Page Assist 已替你处理好该前缀但使用Add Custom Model手动输入模型 ID 时需自行确认 ID 的准确性是否需要前缀取决于你的实际调用方式。::: warning 模型可用性因项目与区域而异 并非所有 Gemini 模型在每个项目、每个区域都可用。尤其是一些较新的 pro 档模型如gemini-3-pro-preview处于gated preview受限预览状态即使模型存在在项目被加入白名单前也会返回404NOT_FOUND——your project does not have access。这是 Google 侧的访问闸门并非 Page Assist 的问题。如需申请访问权限在 Google Cloud Console 的Vertex AI Model Garden中找到该模型使用其中的Enable / Request access功能授权通过后通过Manage Models → Add Custom Model手动添加输入如gemini-3-pro-preview的 ID即可。若模型返回 404可尝试换用其他模型、切换到其他区域或global、或在 Model Garden 中确认访问权限。Gemini 3 的flash档gemini-3.5-flash、gemini-3-flash-preview、gemini-3.1-flash-lite通常无需特殊授权即可使用。 :::五、认证原理纯浏览器内的 JWT → OAuth2 Token 交换Vertex AI 不像 Google AI Studio 那样接受简单 API Key它要求短时的 OAuth2 access token。Page Assist 的目标是全程纯浏览器运行、无需任何本地代理因此实现了完整的「服务账号 JSON → JWT 签名 → 换取 access token」链路核心代码集中在 vertex-auth.ts。5.1 数据边界服务账号 JSON 只本地存储在扩展中除 Google 官方令牌端点oauth2.googleapis.comscope 为https://www.googleapis.com/auth/cloud-platform见 vertex-auth.ts外不会发送到任何其他地址。所有请求直接发往区域化 Vertex AI 端点https://{LOCATION}-aiplatform.googleapis.com/.../endpoints/openapi选择global时使用全局端点。5.2 令牌铸造的完整步骤解析凭据parseServiceAccount()vertex-auth.ts尝试将输入解析为服务账号 JSON若缺少private_key或client_email则判定为「不是服务账号」此时原始字符串被直接当作 access token 使用。构造并签名 JWT使用浏览器 Web Crypto API 的crypto.subtle.importKey/sign以RS256RSASSA-PKCS1-v1_5 SHA-256对{iss, scope, aud, iat, exp}声明签名。JWT 的exp设为当前时间 3600 秒aud指向令牌端点vertex-auth.ts。换取 access token以grant_typeurn:ietf:params:oauth:grant-type:jwt-bearer向令牌端点发起表单请求获得access_tokenvertex-auth.ts。缓存与自动刷新铸得的 token 按client_email缓存在内存Map中vertex-auth.ts并在到期前 60 秒就提前刷新vertex-auth.ts避免临近过期时的竞态。因此日常对话不会对每一次请求都重新签名 JWT。注入模型客户端在 models/index.ts 的vertex分支中getGoogleCloudAccessToken()返回的 token 被作为openAIApiKey与configuration.apiKey传入CustomChatOpenAI从而以 OpenAI 兼容协议直连 Vertex 端点。5.3 快速替代方案直接粘贴原始 access token如果你不想配置服务账号 JSON也可以把原始 access token例如通过gcloud auth print-access-token获取直接粘贴进 Service Account JSON 字段。此时parseServiceAccount()解析失败原始 token 会被原样使用。注意这类 token 大约一小时后过期需要手动更换——因此日常使用仍推荐服务账号 JSON它才能实现自动刷新。六、故障排查401 / 403 / 404 定位指南错误可能原因与处理401 /UNAUTHENTICATEDJSON 未完整粘贴服务账号缺少Vertex AI User角色若粘贴的是原始 access token可能已过期。403 /PERMISSION_DENIED项目未启用 Vertex AI API或服务账号权限不足回到前置条件第 1、2 步检查。404 / model not found确认模型在所选区域可用且模型 ID 正确。部分模型仅限特定区域global覆盖范围最广。另注意 gated preview 模型需在 Model Garden 申请白名单见 4.2 节。七、核心参考文件索引Vertex AI 接入文档本文的原始依据含官方配置步骤与故障排查。认证与工具函数JWT 签名、token 缓存刷新、Base URL 构建、内置模型清单。OpenAI 兼容模型拉取Vertex AI 分支如何返回内置模型清单。模型客户端装配vertex提供方如何注入 access token 构造CustomChatOpenAI。提供方清单vertex提供方的标签与空 Base URL 设计。配置表单实现Project ID 自动填充、Base URL 动态构建与字段校验。配置持久化vertexProjectId/vertexLocation字段定义。按照上述流程完成配置后Page Assist 即可在浏览器内直接、安全地调用你 GCP 项目中的 Gemini 模型用于侧边栏对话、网页问答、知识库检索等场景——全程不依赖任何中转代理。【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考