【免費(fèi)下載鏈接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.項(xiàng)目地址https://gitcode.com/gh_mirrors/op/OpenShell點(diǎn)擊查看免費(fèi)下載本文以 OpenShell 倉庫中的架構(gòu)文檔 architecture/google-vertex-ai-provider.md 為主體結(jié)合 providers/google-vertex-ai.yaml 與crates/下的相關(guān)源碼實(shí)現(xiàn)系統(tǒng)講解google-vertex-aiprovider 的設(shè)計(jì)邊界、兩條憑證接入流、運(yùn)行時(shí)數(shù)據(jù)流與端點(diǎn)約束。讀完本文你將掌握如何在 OpenShell 中為選定沙箱授予對 Google Vertex AIAnthropic Claude、Gemini 及第三方模型的直接訪問能力同時(shí)保證長期 Google 憑證不進(jìn)入沙箱運(yùn)行時(shí)。一、設(shè)計(jì)目標(biāo)憑證與訪問分離google-vertex-aiprovider 的核心設(shè)計(jì)是讓被選中的沙箱直接訪問 Google Vertex AI 端點(diǎn)而不向沙箱暴露任何長期有效的 Google 憑證。這一目標(biāo)通過職責(zé)分離實(shí)現(xiàn)Provider profile 擁有端點(diǎn)策略與憑證元數(shù)據(jù)允許訪問哪些主機(jī)、刷新約束、許可哪些二進(jìn)制沙箱掛載sandbox attachment決定哪個(gè)工作負(fù)載獲得訪問權(quán)。值得注意的是該 provider不選擇模型、不改寫請求體。Anthropic Claude 走 Vertex 的 publisher-modelrawPredict或streamRawPredict路徑Gemini 及其它模型使用 Google 文檔化的原生或 OpenAI 兼容 Vertex API。所有模型選擇、請求格式、流式模式和超時(shí)設(shè)置完全由工作負(fù)載自行決定proxy 只負(fù)責(zé)策略放行與憑證替換。二、組件職責(zé)邊界組件職責(zé)CLI發(fā)現(xiàn) ADC 或接收服務(wù)賬戶引導(dǎo)材料并創(chuàng)建 provider 記錄Gateway通過憑證驅(qū)動(dòng)存儲刷新材料并輪換短時(shí)訪問令牌Provider profile聲明 Vertex 主機(jī)、憑證別名、刷新約束與許可二進(jìn)制Sandbox supervisor下發(fā)不透明憑證占位符僅對 profile 授權(quán)的 Vertex 請求解析為真實(shí)令牌Workload選擇原生 Vertex 端點(diǎn)、模型、請求格式、流式模式與超時(shí)從源碼看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的實(shí)現(xiàn)則在 crates/openshell-providers/src/providers/vertex.rs。三、憑證流兩條路徑匯聚于輪換令牌Vertex 接受 Google 短期 OAuth2 訪問令牌。兩種受支持的接入方式最終都收斂為provider 記錄中存放一個(gè)由 Gateway 輪換的訪問令牌。3.1 服務(wù)賬戶Service account由運(yùn)維人員使用服務(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 中實(shí)現(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策略必須至少聲明一個(gè) scope且private_key必須是 RSA PEM 格式否則直接返回 invalid_argument 錯(cuò)誤。示例 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 小時(shí)。GOOGLE_SERVICE_ACCOUNT_KEY僅是引導(dǎo)材料bootstrap永遠(yuǎn)不會成為沙箱運(yùn)行時(shí)材料的一部分。3.2 gcloud ADC本地開發(fā)針對本地開發(fā)場景CLI 提供--from-gcloud-adc選項(xiàng)流程為讀取授權(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。讀取時(shí)會做嚴(yán)格校驗(yàn)僅接受type: authorized_user的 ADC 文件若發(fā)現(xiàn)type: service_accountCLI 會明確報(bào)錯(cuò)并提示改用服務(wù)賬戶 JSON 密鑰創(chuàng)建 provider缺少client_id、client_secret或refresh_token任一字段都會直接失敗。創(chuàng)建成功后ADC 的client_id、client_secret、refresh_token三項(xiàng)作為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 自動(dòng)發(fā)現(xiàn)--from-existing/ 自動(dòng)創(chuàng)建 provider時(shí)掃描的憑證集合兩條路徑鑄造的訪問令牌通過auth_style: bearerheader_name: authorization聲明在代理層以Authorization: Bearer token頭發(fā)送。四、運(yùn)行時(shí)數(shù)據(jù)流占位符到真實(shí)令牌文檔給出了完整的數(shù)據(jù)流逐條展開掛載運(yùn)維人員將 provider 掛載到沙箱attach策略合成生效策略effective policy包含該 profile 的 Vertex 端點(diǎn)與二進(jìn)制規(guī)則下發(fā)占位符新啟動(dòng)的工作負(fù)載收到當(dāng)前令牌的不透明占位符外加非機(jī)密的 project/region 配置請求發(fā)起工作負(fù)載以占位符作為Authorization: Bearer頭調(diào)用原生 Vertex 端點(diǎn)代理替換策略與端點(diǎn)綁定校驗(yàn)通過后proxy 將占位符替換為當(dāng)前真實(shí)訪問令牌并轉(zhuǎn)發(fā)請求刷新感知令牌刷新更新解析器resolver工作負(fù)載繼續(xù)使用同一個(gè)占位符無需感知輪換。這一占位符 端點(diǎn)綁定解析機(jī)制在 crates/openshell-core/src/provider_credentials.rs 中有清晰的實(shí)現(xiàn)證據(jù)ProviderCredentialState::resolver_and_body_classifier_for_endpoint會按 hostHostPattern、端口與路徑EndpointPathPattern過濾static_credential_bindings只有命中授權(quán)端點(diǎn)的憑證才會被scoped_to_env_keys限定暴露即僅對 profile 授權(quán)的 Vertex 請求解析令牌。文檔同時(shí)強(qiáng)調(diào)原始GOOGLE_SERVICE_ACCOUNT_KEY憑證僅用于引導(dǎo)永不進(jìn)入沙箱運(yùn)行時(shí)材料。五、端點(diǎn)邊界與請求形態(tài)示例 profileproviders/google-vertex-ai.yaml允許四個(gè)官方 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)的原生流式端點(diǎn)streamRawPredict。六、安全不變量Invariants文檔列出的不變量是理解該 provider 安全模型的關(guān)鍵刷新引導(dǎo)材料僅存在于 Gateway沙箱只收到占位符永不收到真實(shí)訪問令牌令牌僅在掛載的 provider profile 覆蓋的端點(diǎn)上解析解綁detach與過期即撤銷占位符解析Project ID、region、publisher、model ID 屬于非機(jī)密工作負(fù)載配置當(dāng) Gateway 全局策略覆蓋抑制了 provider 派生策略時(shí)掛載 provider 不會授予訪問權(quán)同一沙箱掛載多個(gè) provider 時(shí)provider 環(huán)境鍵與動(dòng)態(tài)憑證綁定必須保持無歧義。源碼層面不變量 2/3/4 由上文提到的端點(diǎn)綁定解析器保證不變量 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)境中解析為真實(shí)值的鍵而機(jī)密憑證如訪問令牌保持占位符形態(tài)僅允許在代理時(shí)解析。七、環(huán)境變量注入VertexProvider 的實(shí)現(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 自動(dòng)拾取目標(biāo)項(xiàng)目。此外為兼容沙箱內(nèi) GCP SDK 的啟動(dòng)期探測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 跳過運(yùn)行時(shí) ping并將上述非機(jī)密配置鍵還原為真實(shí)值而機(jī)密令牌保持占位符。八、操作實(shí)踐導(dǎo)入 profile、創(chuàng)建與掛載 provider示例 profile 不會被 OpenShell 自動(dòng)加載需顯式導(dǎo)入且官方建議復(fù)制后編輯而非原樣導(dǎo)入——因?yàn)閎inaries是最小權(quán)限控制的關(guān)鍵必須指明你鏡像中實(shí)際調(diào)用 Vertex 的二進(jìn)制路徑SDK 解釋器、curl 或 agent CLI。# 1) 校驗(yàn) 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)境憑證自動(dòng)創(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)。掛載到沙箱并運(yùn)行端到端驗(yàn)證# 掛載 providersandbox 生命周期操作需在創(chuàng)建沙箱時(shí)或?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 在策略與端點(diǎn)綁定校驗(yàn)通過后替換為真實(shí)令牌。文檔特別提示掛載/解綁使用常規(guī) sandbox provider 生命周期attach/detach運(yùn)行中的沙箱會觀察到策略與解析器變化但必須是在掛載后啟動(dòng)的進(jìn)程才能拿到新的環(huán)境變量直接原生請求是端到端驗(yàn)證路徑創(chuàng)建 provider 不會探測模型端點(diǎn)也不會校驗(yàn) model ID 的有效性。若想驗(yàn)證沙箱當(dāng)前掛載的 provider可運(yùn)行openshell sandbox providers list對應(yīng)源碼中的list_sandbox_providers路徑解綁使用 detach 操作解綁后占位符解析即被撤銷滿足不變量 4。九、適用前提與注意事項(xiàng)本文描述的配置基于當(dāng)前倉庫providers/google-vertex-ai.yaml實(shí)際內(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 時(shí)通過VERTEX_AI_PROJECT_ID/VERTEX_AI_REGION配置鍵提供了值可查看openshell provider create --help了解配置鍵寫法。若你的鏡像中調(diào)用 Vertex 的客戶端不在 profile 的binaries白名單內(nèi)二進(jìn)制級流量歸屬將不生效——請務(wù)必按實(shí)際鏡像內(nèi)容補(bǔ)充binaries列表這是該 profile 的最小權(quán)限基石。十、小結(jié)google-vertex-aiprovider 通過Gateway 持有長期材料、沙箱只持有占位符、代理層按端點(diǎn)綁定解析真實(shí)令牌的三層模型在安全與便利之間取得了平衡工作負(fù)載獲得了對 Vertex 的原生、直接訪問而長期 Google 憑證始終留在 Gateway 憑證庫中。配合 provider profile 的端點(diǎn)白名單與二進(jìn)制許可該機(jī)制可作為 OpenShell 中受控接入外部 AI 推理服務(wù)的參考范式。贊分享【免費(fèi)下載鏈接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.項(xiàng)目地址https://gitcode.com/gh_mirrors/op/OpenShell點(diǎn)擊查看免費(fèi)下載相關(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)與實(shí)戰(zhàn)langchaingo 中 Google 模型提供者完全指南googleai、Vertex AI 與 PaLM 的架構(gòu)與實(shí)戰(zhàn) 本指南以 llms/google人工智能大模型AI AgentRAG后端ZenML Vertex AI Step Operator 實(shí)戰(zhàn)指南將流水線單步調(diào)度到 Google Cloud Vertex AI 執(zhí)行ZenML Vertex AI Step Operator 實(shí)戰(zhàn)指南將流水線單步調(diào)度到 Google Cloud Vertex AI 執(zhí)行 ZenML 的 VMLOps機(jī)器學(xué)習(xí)后端工作流自動(dòng)化AI Agent上一篇如何快速檢測OpenSpeedy內(nèi)存問題AddressSanitizer完整使用指南下一篇Red-Teaming-Toolkit第三方依賴項(xiàng)目使用的外部庫與工具創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考