【免費下載鏈接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.項目地址https://gitcode.com/gh_mirrors/op/OpenShell點擊查看免費下載本文以 OpenShell 倉庫中的架構(gòu)文檔 architecture/google-vertex-ai-provider.md 為主體結(jié)合 providers/google-vertex-ai.yaml 與crates/下的相關(guān)源碼實現(xiàn)系統(tǒng)講解google-vertex-aiprovider 的設(shè)計邊界、兩條憑證接入流、運行時數(shù)據(jù)流與端點約束。讀完本文你將掌握如何在 OpenShell 中為選定沙箱授予對 Google Vertex AIAnthropic Claude、Gemini 及第三方模型的直接訪問能力同時保證長期 Google 憑證不進(jìn)入沙箱運行時。一、設(shè)計目標(biāo)憑證與訪問分離google-vertex-aiprovider 的核心設(shè)計是讓被選中的沙箱直接訪問 Google Vertex AI 端點而不向沙箱暴露任何長期有效的 Google 憑證。這一目標(biāo)通過職責(zé)分離實現(xiàn)Provider profile 擁有端點策略與憑證元數(shù)據(jù)允許訪問哪些主機(jī)、刷新約束、許可哪些二進(jìn)制沙箱掛載sandbox attachment決定哪個工作負(fù)載獲得訪問權(quán)。值得注意的是該 provider不選擇模型、不改寫請求體。Anthropic Claude 走 Vertex 的 publisher-modelrawPredict或streamRawPredict路徑Gemini 及其它模型使用 Google 文檔化的原生或 OpenAI 兼容 Vertex API。所有模型選擇、請求格式、流式模式和超時設(shè)置完全由工作負(fù)載自行決定proxy 只負(fù)責(zé)策略放行與憑證替換。二、組件職責(zé)邊界組件職責(zé)CLI發(fā)現(xiàn) ADC 或接收服務(wù)賬戶引導(dǎo)材料并創(chuàng)建 provider 記錄Gateway通過憑證驅(qū)動存儲刷新材料并輪換短時訪問令牌Provider profile聲明 Vertex 主機(jī)、憑證別名、刷新約束與許可二進(jìn)制Sandbox supervisor下發(fā)不透明憑證占位符僅對 profile 授權(quán)的 Vertex 請求解析為真實令牌Workload選擇原生 Vertex 端點、模型、請求格式、流式模式與超時從源碼看CLI 側(cè)的職責(zé)落在 crates/openshell-cli/src/commands/provider.rs它通過discover_from_profile發(fā)現(xiàn)本地已有憑證crates/openshell-providers/src/discovery.rs并通過read_gcloud_adc()解析 gcloud ADC 文件VertexProvider的實現(xiàn)則在 crates/openshell-providers/src/providers/vertex.rs。三、憑證流兩條路徑匯聚于輪換令牌Vertex 接受 Google 短期 OAuth2 訪問令牌。兩種受支持的接入方式最終都收斂為provider 記錄中存放一個由 Gateway 輪換的訪問令牌。3.1 服務(wù)賬戶Service account由運維人員使用服務(wù)賬戶引導(dǎo)材料創(chuàng)建 provider并配置google-service-account-jwt刷新策略私鑰保留在 Gateway 憑證庫中絕不進(jìn)入沙箱Gateway 鑄造GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN并在其過期前刷新。該策略在 crates/openshell-server/src/provider_refresh.rs 中實現(xiàn)mint_google_service_account_jwt使用 RSA PEM 私鑰以 RS256 算法簽名 JWTclaims 含issclient_email、scope、audtoken_url、iat/exp隨后以grant_typeurn:ietf:params:oauth:grant-type:jwt-bearer向https://oauth2.googleapis.com/token換取訪問令牌。源碼注釋明確要求google_service_account_jwt策略必須至少聲明一個 scope且private_key必須是 RSA PEM 格式否則直接返回 invalid_argument 錯誤。示例 profile 中該策略的完整配置見 providers/google-vertex-ai.yaml- name: service_account_token description: Google Cloud access token refreshed from service account JWT material env_vars: [GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN, VERTEX_AI_SERVICE_ACCOUNT_TOKEN] required: false auth_style: bearer header_name: authorization refresh: strategy: google_service_account_jwt token_url: https://oauth2.googleapis.com/token scopes: [https://www.googleapis.com/auth/cloud-platform] refresh_before_seconds: 300 max_lifetime_seconds: 3600 material: - name: client_email # Google 服務(wù)賬戶郵箱必填 - name: private_key # Google 服務(wù)賬戶私鑰必填secret: true - name: subject # 可選域級委托的委托用戶郵箱refresh_before_seconds: 300表示在令牌到期前 300 秒提前刷新max_lifetime_seconds: 3600限制令牌最長壽命為 1 小時。GOOGLE_SERVICE_ACCOUNT_KEY僅是引導(dǎo)材料bootstrap永遠(yuǎn)不會成為沙箱運行時材料的一部分。3.2 gcloud ADC本地開發(fā)針對本地開發(fā)場景CLI 提供--from-gcloud-adc選項流程為讀取授權(quán)用戶authorized-user類型的 ADC 文件將刷新授權(quán)refresh grant存儲到 GatewayGateway 鑄造GOOGLE_VERTEX_AI_TOKENADC 文件與刷新令牌均不進(jìn)入沙箱。ADC 文件的查找順序見 crates/openshell-cli/src/commands/provider.rsGOOGLE_APPLICATION_CREDENTIALS環(huán)境變量指定的路徑CLOUDSDK_CONFIG目錄下的application_default_credentials.json默認(rèn)的$HOME/.config/gcloud/application_default_credentials.json。讀取時會做嚴(yán)格校驗僅接受type: authorized_user的 ADC 文件若發(fā)現(xiàn)type: service_accountCLI 會明確報錯并提示改用服務(wù)賬戶 JSON 密鑰創(chuàng)建 provider缺少client_id、client_secret或refresh_token任一字段都會直接失敗。創(chuàng)建成功后ADC 的client_id、client_secret、refresh_token三項作為oauth2_refresh_token策略的 material 存入 Gateway。對應(yīng) profile 中的配置- name: gcloud_adc_token description: Google Cloud access token refreshed via gcloud Application Default Credentials env_vars: [GOOGLE_VERTEX_AI_TOKEN, VERTEX_AI_TOKEN] required: false auth_style: bearer header_name: authorization refresh: strategy: oauth2_refresh_token token_url: https://oauth2.googleapis.com/token scopes: [https://www.googleapis.com/auth/cloud-platform] refresh_before_seconds: 300 max_lifetime_seconds: 3600 material: - name: client_id # gcloud ADC 中的 Google OAuth2 client ID必填 - name: client_secret # gcloud ADC 中的 Google OAuth2 client secret必填secret: true - name: refresh_token # gcloud ADC 中的 Google OAuth2 refresh token必填secret: truediscovery.credentials: [service_account_token, gcloud_adc_token]聲明了 CLI 自動發(fā)現(xiàn)--from-existing/ 自動創(chuàng)建 provider時掃描的憑證集合兩條路徑鑄造的訪問令牌通過auth_style: bearerheader_name: authorization聲明在代理層以Authorization: Bearer token頭發(fā)送。四、運行時數(shù)據(jù)流占位符到真實令牌文檔給出了完整的數(shù)據(jù)流逐條展開掛載運維人員將 provider 掛載到沙箱attach策略合成生效策略effective policy包含該 profile 的 Vertex 端點與二進(jìn)制規(guī)則下發(fā)占位符新啟動的工作負(fù)載收到當(dāng)前令牌的不透明占位符外加非機(jī)密的 project/region 配置請求發(fā)起工作負(fù)載以占位符作為Authorization: Bearer頭調(diào)用原生 Vertex 端點代理替換策略與端點綁定校驗通過后proxy 將占位符替換為當(dāng)前真實訪問令牌并轉(zhuǎn)發(fā)請求刷新感知令牌刷新更新解析器resolver工作負(fù)載繼續(xù)使用同一個占位符無需感知輪換。這一占位符 端點綁定解析機(jī)制在 crates/openshell-core/src/provider_credentials.rs 中有清晰的實現(xiàn)證據(jù)ProviderCredentialState::resolver_and_body_classifier_for_endpoint會按 hostHostPattern、端口與路徑EndpointPathPattern過濾static_credential_bindings只有命中授權(quán)端點的憑證才會被scoped_to_env_keys限定暴露即僅對 profile 授權(quán)的 Vertex 請求解析令牌。文檔同時強(qiáng)調(diào)原始GOOGLE_SERVICE_ACCOUNT_KEY憑證僅用于引導(dǎo)永不進(jìn)入沙箱運行時材料。五、端點邊界與請求形態(tài)示例 profileproviders/google-vertex-ai.yaml允許四個官方 Vertex 主機(jī)全部為 443 端口、rest 協(xié)議、read-write 訪問、enforcement: enforce強(qiáng)制 L7 檢查*-aiplatform.googleapis.com區(qū)域主機(jī)如us-central1-aiplatform.googleapis.comaiplatform.googleapis.com全局主機(jī)aiplatform.us.rep.googleapis.com美國副本主機(jī)aiplatform.eu.rep.googleapis.com歐洲副本主機(jī)工作負(fù)載自行構(gòu)造 project、location、publisher、model 路徑proxy 不推斷 publisher也不改寫請求體。Claude on Vertex 的請求形態(tài)如下https://location-aiplatform.googleapis.com/v1/projects/project/locations/location/publishers/anthropic/models/model:rawPredict請求體包含 Google 要求的 Vertex Anthropic API 版本流式請求走對應(yīng)的原生流式端點streamRawPredict。六、安全不變量Invariants文檔列出的不變量是理解該 provider 安全模型的關(guān)鍵刷新引導(dǎo)材料僅存在于 Gateway沙箱只收到占位符永不收到真實訪問令牌令牌僅在掛載的 provider profile 覆蓋的端點上解析解綁detach與過期即撤銷占位符解析Project ID、region、publisher、model ID 屬于非機(jī)密工作負(fù)載配置當(dāng) Gateway 全局策略覆蓋抑制了 provider 派生策略時掛載 provider 不會授予訪問權(quán)同一沙箱掛載多個 provider 時provider 環(huán)境鍵與動態(tài)憑證綁定必須保持無歧義。源碼層面不變量 2/3/4 由上文提到的端點綁定解析器保證不變量 5 在 crates/openshell-core/src/google_cloud.rs 中體現(xiàn)——STATIC_CONFIG_KEYS將GCP_PROJECT_ID、GOOGLE_CLOUD_PROJECT、CLOUD_ML_REGION、GCP_LOCATION、GOOSE_PROVIDER、ANTHROPIC_VERTEX_PROJECT_ID、VERTEX_LOCATION等非機(jī)密配置定義為必須在子環(huán)境中解析為真實值的鍵而機(jī)密憑證如訪問令牌保持占位符形態(tài)僅允許在代理時解析。七、環(huán)境變量注入VertexProvider 的實現(xiàn)細(xì)節(jié)VertexProvidercrates/openshell-providers/src/providers/vertex.rs負(fù)責(zé)把非機(jī)密配置注入沙箱環(huán)境配置鍵VERTEX_AI_PROJECT_ID注入GCP_PROJECT_ID、GOOGLE_CLOUD_PROJECTalias 數(shù)組見 crates/openshell-core/src/google_cloud.rs 的PROJECT_ID_ENV_VARS并額外注入 Claude Code SDK 讀取的ANTHROPIC_VERTEX_PROJECT_ID配置鍵VERTEX_AI_REGION注入CLOUD_ML_REGION、GCP_LOCATION以及VERTEX_LOCATION注入GOOSE_PROVIDERgcp_vertex_ai用于向 Goose 標(biāo)識 Vertex AI 場景不覆蓋已存在的環(huán)境變量or_insert_with語義且跳過空值/純空白配置。以上行為均有對應(yīng)單元測試injects_project_id_and_anthropic_alias、injects_region_and_vertex_location、does_not_overwrite_existing_env、skips_empty_config_values等。profile 頭部注釋還提示VERTEX_AI_PROJECT_ID與VERTEX_AI_REGION會被投影進(jìn)沙箱供 SDK 與 agent CLI 自動拾取目標(biāo)項目。此外為兼容沙箱內(nèi) GCP SDK 的啟動期探測provider_credentials.rs中的child_env_with_gcp_resolved會注入GCE_METADATA_IP指向127.0.0.1:8174的元數(shù)據(jù)模擬器回環(huán)地址與METADATA_SERVER_DETECTIONassume-present供 Node.js 的 gcp-metadata 跳過運行時 ping并將上述非機(jī)密配置鍵還原為真實值而機(jī)密令牌保持占位符。八、操作實踐導(dǎo)入 profile、創(chuàng)建與掛載 provider示例 profile 不會被 OpenShell 自動加載需顯式導(dǎo)入且官方建議復(fù)制后編輯而非原樣導(dǎo)入——因為binaries是最小權(quán)限控制的關(guān)鍵必須指明你鏡像中實際調(diào)用 Vertex 的二進(jìn)制路徑SDK 解釋器、curl 或 agent CLI。# 1) 校驗 profile 語法 openshell provider profile lint -f providers/google-vertex-ai.yaml # 2) 導(dǎo)入為全局 profile openshell provider profile import -f providers/google-vertex-ai.yaml --global # 3) 用 gcloud ADC 創(chuàng)建 provider本地開發(fā) openshell provider create --type google-vertex-ai --name vertex-ai --from-gcloud-adc # 或使用已存在的環(huán)境憑證自動創(chuàng)建 openshell provider create --type google-vertex-ai --name vertex-ai --from-existing說明CLI 對google-vertex-ai類型的憑證解析會依次查找GOOGLE_VERTEX_AI_TOKEN、VERTEX_AI_TOKEN、GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN、VERTEX_AI_SERVICE_ACCOUNT_TOKEN見 crates/openshell-cli/src/commands/provider.rs 的missing_credentials_error也可直接用--from-gcloud-adc引導(dǎo)。掛載到沙箱并運行端到端驗證# 掛載 providersandbox 生命周期操作需在創(chuàng)建沙箱時或?qū)ΜF(xiàn)有沙箱執(zhí)行 openshell sandbox create --provider vertex-ai -- \ curl -sS -H Authorization: Bearer $GOOGLE_VERTEX_AI_TOKEN \ https://us-central1-aiplatform.googleapis.com/v1/projects/$VERTEX_AI_PROJECT_ID/locations/us-central1/publishers/google/modelsprofile 注釋中給出的 smoke test 即以上形式在沙箱內(nèi)用GOOGLE_VERTEX_AI_TOKEN占位符發(fā)起原生請求由 proxy 在策略與端點綁定校驗通過后替換為真實令牌。文檔特別提示掛載/解綁使用常規(guī) sandbox provider 生命周期attach/detach運行中的沙箱會觀察到策略與解析器變化但必須是在掛載后啟動的進(jìn)程才能拿到新的環(huán)境變量直接原生請求是端到端驗證路徑創(chuàng)建 provider 不會探測模型端點也不會校驗 model ID 的有效性。若想驗證沙箱當(dāng)前掛載的 provider可運行openshell sandbox providers list對應(yīng)源碼中的list_sandbox_providers路徑解綁使用 detach 操作解綁后占位符解析即被撤銷滿足不變量 4。九、適用前提與注意事項本文描述的配置基于當(dāng)前倉庫providers/google-vertex-ai.yaml實際內(nèi)容Token 刷新參數(shù)refresh_before_seconds、max_lifetime_seconds、scopes可按需在復(fù)制的 profile 中調(diào)整但務(wù)必理解其安全含義縮短max_lifetime_seconds可降低令牌泄漏窗口scopes決定了令牌在 Google 側(cè)的權(quán)限面。服務(wù)賬戶方式適合生產(chǎn)與無人值守場景私鑰只在 Gateway 側(cè)gcloud ADC 方式僅適合本地開發(fā)依賴用戶授權(quán)。沙箱內(nèi)工作負(fù)載如需使用$VERTEX_AI_PROJECT_ID等變量前提是創(chuàng)建 provider 時通過VERTEX_AI_PROJECT_ID/VERTEX_AI_REGION配置鍵提供了值可查看openshell provider create --help了解配置鍵寫法。若你的鏡像中調(diào)用 Vertex 的客戶端不在 profile 的binaries白名單內(nèi)二進(jìn)制級流量歸屬將不生效——請務(wù)必按實際鏡像內(nèi)容補(bǔ)充binaries列表這是該 profile 的最小權(quán)限基石。十、小結(jié)google-vertex-aiprovider 通過Gateway 持有長期材料、沙箱只持有占位符、代理層按端點綁定解析真實令牌的三層模型在安全與便利之間取得了平衡工作負(fù)載獲得了對 Vertex 的原生、直接訪問而長期 Google 憑證始終留在 Gateway 憑證庫中。配合 provider profile 的端點白名單與二進(jìn)制許可該機(jī)制可作為 OpenShell 中受控接入外部 AI 推理服務(wù)的參考范式。贊分享【免費下載鏈接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.項目地址https://gitcode.com/gh_mirrors/op/OpenShell點擊查看免費下載相關(guān)推薦VoltAgent Google AI Provider 集成指南基于 Gemini API 與 Vertex AI 的 Agent 構(gòu)建與遷移VoltAgent Google AI Provider 集成指南基于 Gemini API 與 Vertex AI 的 Agent 構(gòu)建與遷移 volta人工智能AI AgentAgent 框架后端多智能體RAG工具調(diào)用Agent 記憶Agent 工作流AI 評測MCP 服務(wù)MCP Clients語音langchaingo 中 Google 模型提供者完全指南googleai、Vertex AI 與 PaLM 的架構(gòu)與實戰(zhàn)langchaingo 中 Google 模型提供者完全指南googleai、Vertex AI 與 PaLM 的架構(gòu)與實戰(zhàn) 本指南以 llms/google人工智能大模型AI AgentRAG后端ZenML Vertex AI Step Operator 實戰(zhàn)指南將流水線單步調(diào)度到 Google Cloud Vertex AI 執(zhí)行ZenML Vertex AI Step Operator 實戰(zhàn)指南將流水線單步調(diào)度到 Google Cloud Vertex AI 執(zhí)行 ZenML 的 VMLOps機(jī)器學(xué)習(xí)后端工作流自動化AI Agent上一篇如何快速檢測OpenSpeedy內(nèi)存問題AddressSanitizer完整使用指南下一篇Red-Teaming-Toolkit第三方依賴項目使用的外部庫與工具創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考