Parlant Vertex AI 适配器实战在 GCP 上为面向客户的 Agent 接入 Claude 与 Gemini 双模型【免费下载链接】parlantBuild reliable customer-facing AI agents with Parlant: an interaction control harness optimized for controlled, consistent, and predictable LLM interactions.项目地址: https://gitcode.com/GitHub_Trending/pa/parlantParlant 的 Vertex AI 适配器让面向客户customer-facing的 AI Agent 可以直接运行在 Google Cloud Vertex AI 平台上同时支持 Anthropic Claude 与 Google Gemini 两条模型路线并在统一的NLPService接口下提供文本生成、向量嵌入与 Token 估算三项能力。读完本文你将掌握该适配器的环境配置与认证方式、9 个受支持模型的完整映射关系、源码层面的模型路由与回退机制、JSON 结构化输出与重试策略的实现细节以及一套可落地的故障排查与迁移方案。定位与核心架构Vertex AI 适配器是 Parlant 众多 NLP 服务适配器之一其核心实现集中在 vertex_service.py 一个文件中官方文档见 vertex.md。它实现了 Parlant 的NLPService抽象接口为引擎提供三条能力线结构化文本生成Schematic Generation所有对话决策guideline 匹配、journey 节点选择、工具调用等都依赖模型按 Pydantic Schema 输出 JSON这是该适配器的主要工作负载文本嵌入Embedding用于 guideline、术语等内容的索引与检索Token 估算Tokenization用于上下文长度控制。从源码结构看五个核心组件的分工如下组件源码位置职责VertexAIServicevertex_service.py#L680主服务类实现NLPService接口负责模型路由与工厂方法VertexAIClaudeSchematicGeneratorvertex_service.py#L127Claude 模型生成器走 Anthropic Vertex APIAsyncAnthropicVertex客户端VertexAIGeminiSchematicGeneratorvertex_service.py#L278Gemini 模型生成器走 Google Gen AI APIgoogle.genai.ClientVertexAIEmbedder/VertexTextEmbedding004vertex_service.py#L571基于text-embedding-004的嵌入服务768 维VertexAIEstimatingTokenizervertex_service.py#L86Token 计数Claude 用 tiktoken 估算Gemini 调用官方count_tokens接口一个值得注意的设计两条模型路线共用同一个适配器、同一套认证GCP ADC只是根据模型名选择不同的 SDK 客户端。模型提供者的判定逻辑非常简单按模型名字符串判断def get_model_provider(model_name: str) - ModelProvider: Determine the model provider based on model name. if claude in model_name.lower(): return ModelProvider.ANTHROPIC elif gemini in model_name.lower(): return ModelProvider.GOOGLE else: raise ValueError(fUnknown model provider for model: {model_name})该逻辑见 vertex_service.py#L117-L124。安装与前置依赖使用 Vertex AI 适配器需要安装对应的可选依赖extraspip install parlant[vertex]从 pyproject.toml 看vertexextra 实际安装的依赖及其版本下限为vertex [ google-genai1.36.0, google-api-core2.24.2, google-auth2.40.0, torch2.8.0, anthropic0.60.0, transformers4.53.0, ]其中google-genai服务 Gemini 路线与嵌入anthropic提供AsyncAnthropicVertex客户端服务 Claude 路线google-auth负责读取 Application Default CredentialsADC。配置环境变量与认证必需的环境变量export VERTEX_AI_PROJECT_IDyour-gcp-project-id export VERTEX_AI_REGIONus-central1 # 替换为你的区域 export VERTEX_AI_MODELclaude-opus-4VERTEX_AI_MODEL可以填短名如claude-sonnet-3.5也可以填带版本后缀的完整模型名适配器会通过_normalize_model_name把短名映射到全名见下文模型表。关于默认值有一个源码层面的细节VertexAIService.__init__读取环境变量时给出了默认值——region 缺省为us-central1model 缺省为claude-sonnet-3.5见 vertex_service.py#L746-L750。但通过 SDK 方式创建服务时不存在缺省可用的情况NLPServices.vertex会先调用verify_environment()检查三个变量是否齐全、再调用validate_adc()检查 ADC 是否可加载任一失败都会抛出NLPServiceConfigurationError见 sdk.py#L478-L490。ADC 认证适配器使用 Google Application Default Credentials# 本地开发 gcloud auth application-default login # 验证认证是否生效 gcloud auth application-default print-access-token # 生产环境建议使用服务账号密钥或 Workload Identity源码中 ADC 校验直接调用google.auth.default()失败时返回的错误信息明确提示运行gcloud auth application-default login见 vertex_service.py#L723-L739。所需 IAM 权限确保服务账号或用户具备以下角色Vertex AI User—— 访问 Vertex AI 服务AI Platform User—— 部分模型尤其遗留模型可能仍需要该角色。受支持的模型Claude 模型经 Anthropic Vertex API短名完整模型名说明claude-opus-4claude-opus-420250514能力最强的 Claude 模型带 Sonnet 4 回退claude-sonnet-4claude-sonnet-420250514性能与速度均衡claude-sonnet-3.5claude-3-5-sonnet-v220241022上一代 Sonnetclaude-haiku-3.5claude-3-5-haiku20241022最快的 Claude 模型Gemini 模型经 Google Gen AI API短名完整模型名说明gemini-2.5-flashgemini-2.5-flash最新快速模型默认禁用 thinkinggemini-2.5-progemini-2.5-pro最新 Pro 模型gemini-2.0-flashgemini-2.0-flash上一代 Flashgemini-1.5-flashgemini-1.5-flash1M token 上下文gemini-1.5-progemini-1.5-pro2M token 上下文这两张表与源码中的两个类级映射字典完全对应CLAUDE_MODELS与GEMINI_MODELS见 vertex_service.py#L683-L696。模型弃用提示原文档说明Claude Sonnet 3.5 模型claude-3-5-sonnet-20240620与claude-3-5-sonnet-20241022已于 2025 年 10 月 22 日退役建议迁移到 Claude Sonnet 4claude-sonnet-4-20250514。使用方式SDK 快速接入推荐的接入方式是通过NLPServices.vertex工厂方法。仓库自带的 healthcare.py 示例展示了典型用法import parlant.sdk as p from parlant.sdk import NLPServices async with p.Server(nlp_serviceNLPServices.vertex) as server: agent await server.create_agent( nameHealthcare Agent, descriptionIs empathetic and calming to the patient., )如 healthcare.py#L165-L170 所示p.Server()在传入nlp_serviceNLPServices.vertex后整个引擎guideline 匹配、journey 状态机、工具调用即运行在 Vertex AI 之上Agent 配置代码无需任何改动。直接调用服务进阶也可以绕过 SDK 容器直接操作VertexAIService。注意实际构造函数需要logger、tracer、meter、health_reporter四个依赖见 vertex_service.py#L741-L761from parlant.adapters.nlp.vertex_service import VertexAIService from pydantic import BaseModel class MySchema(BaseModel): answer: str # service 由容器/工厂创建后 generator await service.get_schematic_generator(MySchema) result await generator.generate( promptYour prompt here, hints{temperature: 0.7, max_tokens: 1000} )生成结果SchematicGenerationResult包含两部分按 Schema 校验后的contentPydantic 模型实例以及info模型 ID、耗时、输入/输出 token 用量。源码深潜模型路由、回退与默认分支get_schematic_generator是整个适配器的路由中枢见 vertex_service.py#L784-L908。先经_normalize_model_name把短名解析为完整模型名再由get_model_provider分流到 Anthropic 或 Google 两条链路最后按模型名字符串匹配到具体生成器claude-opus-4的特殊回退机制当模型名包含opus-4时返回的不是单个生成器而是FallbackSchematicGenerator——主生成器为VertexClaudeOpus4回退生成器为VertexClaudeSonnet4见 vertex_service.py#L791-L811。这意味着在 Opus 4 不可用例如配额耗尽、区域未开通时生成请求会自动落到 Sonnet 4 上这是文档中Maximum capability with fallback说法的源码依据。未匹配时的默认分支Claude 路线无法匹配任何已知模型时默认落到VertexClaudeSonnet35Sonnet 3.5Gemini 路线则默认落到VertexGemini25Flash。换言之填入一个完整的自定义模型名也能跑通只是生成器会按上述默认类实例化。gemini-2.5-flash 的 thinking 行为VertexGemini25Flash覆写了generate在调用前强制注入{thinking_config: {thinking_budget: 0}}用户 hints 可覆盖即默认关闭推理模型的思考预算以换取速度见 vertex_service.py#L541-L550。Token 估算的双实现VertexAIEstimatingTokenizervertex_service.py#L86-L114按模型路线采用两种完全不同的策略Claude 路线本地用 tiktokengpt-4o-2024-08-06编码编码后取len(tokens) * 1.15作为保守估计值——放大系数是为覆盖 Anthropic 分词与 OpenAI 分词的差异源码注释标注该做法与 Bedrock 适配器一致Gemini 路线调用 Google Gen AI 的aio.models.count_tokens接口获取真实计数嵌入模型text-embedding-004没有对应计数端点则借用gemini-2.5-pro来估算。上下文上限也按路线区分Claude 生成器max_tokens固定返回 200,000Gemini 生成器按模型名判断——含flash返回 1M否则返回 2M见 vertex_service.py#L309-L315。两条路线的 JSON 结构化输出处理生成器都要求模型输出符合 Pydantic Schema 的 JSON但两条路线的约束强度不同Gemini 路线使用原生 Schema 约束_do_generate在config中同时设置response_mime_type: application/json与response_schema: self.schema.model_json_schema()见 vertex_service.py#L349-L353由服务端保证 JSON 格式。Claude 路线则依赖提示词约束 后置提取用normalize_json_output归一化后用jsonfinder.only_json从原始文本中抽出 JSON 对象再做schema.model_validate校验见 vertex_service.py#L239-L275。两条路线都有清洗步骤——Gemini 路线额外修复了弯引号smart quotes与双重转义的\u/\t/\n序列vertex_service.py#L391-L400。校验失败会记录包含原始输出的错误日志并抛出ValidationError便于定位模型输出问题。hints 支持与默认值生成器supported_hints说明Claudetemperature、max_tokens、top_p、top_kmax_tokens缺省 8192messages.create调用处默认值Geminitemperature、thinking_configthinking_config用于推理模型2.5-flash 默认thinking_budget0Embeddertitle、task_typetask_type缺省RETRIEVAL_DOCUMENT不属于supported_hints的 hints 会被过滤掉{k: v for k, v in hints.items() if k in self.supported_hints}因此传入未知参数不会导致 API 报错但也不会生效。嵌入服务text-embedding-004VertexAIEmbedder通过 Google Gen AI 的embed_content接口生成向量关键参数如下见 vertex_service.py#L571-L667idvertex-ai/text-embedding-004dimensions固定768由子类VertexTextEmbedding004覆写见 vertex_service.py#L670-L677max_tokens8192单条输入 token 上限task_type默认RETRIEVAL_DOCUMENT可经 hints 覆盖同时支持titlehint 提供文档标题以提升嵌入质量。注意VertexAIEmbedder.__init__会硬校验VERTEX_AI_PROJECT_ID环境变量缺失时直接抛ValueErrorregion 则取VERTEX_AI_REGION且缺省us-central1见 vertex_service.py#L584-L597。重试策略与错误处理分层重试策略适配器使用 Parlant 自带的policyretry装饰器定义于 policies.py实现异常级重试。两条生成路线的策略完全对称层目标异常最大重试退避间隔第一层ClaudeAPIConnectionError、APITimeoutError、RateLimitError、APIResponseValidationError3 次1s → 2s → 4s第二层ClaudeInternalServerError2 次1s → 5s第一层GeminiNotFound、TooManyRequests、ResourceExhausted3 次1s → 2s → 4s第二层GeminiServerError2 次1s → 5s策略声明位置Claude 见 vertex_service.py#L169-L183Gemini 见 vertex_service.py#L317-L330。嵌入接口仅配置了第一层NotFound/TooManyRequests/ResourceExhausted3 次见 vertex_service.py#L615-L627。认证异常源码定义了专门的异常类class VertexAIAuthError(Exception): Raised when there are authentication issues with Vertex AI.见 vertex_service.py#L80-L83。常见原因与对策缺少 ADC运行gcloud auth application-default login权限不足确认具备Vertex AI User角色模型未开通在 Vertex AI Model Garden 中启用对应模型。运行期错误信息适配器对两类高频故障打印了可直接照做的排查指引限流Rate Limit Exceeded——Claude 路线捕获RateLimitError后输出Gemini 路线对TooManyRequests输出同构信息要点包括GCP 项目配额不足、模型未在 Model Garden 启用、超出每分钟请求数建议检查 GCP Console 配额、确认模型启用状态、复查服务账号 IAM 权限。权限拒绝403 / permission——按异常文本中是否含403或permission判定输出三步检查ADC 是否配置、服务账号是否有Vertex AI User角色、具体模型是否已启用见 vertex_service.py#L224-L233。使用异常处理的代码范式from parlant.adapters.nlp.vertex_service import VertexAIAuthError try: generator await service.get_schematic_generator(MySchema) result await generator.generate(prompt) except VertexAIAuthError as e: logger.error(fAuthentication failed: {e}) # 处理认证配置 except Exception as e: logger.error(fGeneration failed: {e}) # 处理其他错误用量观测Claude 路线在每次成功生成后通过record_llm_metrics上报输入/输出 tokenvertex_service.py#L251-L257Gemini 路线除 token 用量外还会把cached_content_token_count记录进UsageInfo.extra并把完整的usage_metadata以 trace 级别写入日志vertex_service.py#L405-L431。原文档提示的排查入口是在 Parlant playground UI 中检查生成的消息即可看到用量明细。性能与选型建议上下文上限模型类型上下文上限建议用途Claude 全系200K tokens长文档、复杂推理Gemini Flash1M tokens大上下文处理Gemini Pro2M tokens超大上下文需求模型选择建议原文档 Best PracticesClaude Sonnet 3.5性能与成本的最佳平衡注意退役时间线新部署建议直接用 Sonnet 4Claude Opus 4能力上限最高且自带 Sonnet 4 回退Gemini 2.5 Flash大上下文 快速处理thinking 默认关闭Gemini 2.5 Pro复杂推理任务。源码文件头部注释也给出了官方倾向Use gemini-2.5-pro and claude sonnet 4 models for best results见 vertex_service.py#L18。两个功能限制需要知悉supports_streaming固定返回False调用流式接口会抛NotImplementedErrorvertex_service.py#L763-L772get_moderation_service当前返回NoModeration内容审核尚未在该适配器中实现vertex_service.py#L920-L923。故障排查清单症状排查步骤认证失败gcloud auth application-default print-access-token验证 ADC检查 GCP Console 项目权限确认服务账号角色模型访问被拒在 Model Garden 启用模型确认区域可用性确认计费账户已激活限流在 GCP Console 监控配额使用在应用层限流评估升级服务等级日志定位生成器以Vertex LLM Request ({schema})为日志作用域名logger.scope可按 Schema 名过滤单次请求全链路从其他 NLP 适配器迁移从 OpenAI / Anthropic 直连等适配器迁移到 Vertex AI 时只需两步1. 替换环境变量# 移除旧变量 unset OPENAI_API_KEY ANTHROPIC_API_KEY # 设置 Vertex AI 变量 export VERTEX_AI_PROJECT_IDyour-project-id export VERTEX_AI_REGIONus-central1 export VERTEX_AI_MODELclaude-opus-42. 模型名映射原文档建议原模型迁移目标gpt-4claude-opus-4gpt-3.5-turbogemini-2.5-flashclaude-3-sonnetclaude-opus-4代码侧仅需把p.Server(nlp_service...)换为NLPServices.vertexAgent、journey、guideline 等配置全部保持不变。扩展新增模型的维护路径如果你需要为该适配器添加新模型原文档给出的维护流程与源码结构一一对应确定提供路线模型名含claude走 Anthropic API含gemini走 Google APIget_model_provider的判定规则决定了模型名必须包含相应子串创建模型子类仿照VertexClaudeSonnet4/VertexGemini25Pro等现有类继承对应基类并固定model_name更新服务映射把短名加入CLAUDE_MODELS或GEMINI_MODELS并在get_schematic_generator中增加对应分支补充测试为新模型加入集成测试更新文档把模型加入受支持模型表。代码规范要求沿用现有错误处理模式、保留完整日志、为所有方法添加类型注解、用 docstring 记录公开 API、对外部 API 调用一律配置重试策略。小结Parlant 的 Vertex AI 适配器用单一入口NLPServices.vertex 三个环境变量覆盖了 Claude 与 Gemini 双模型栈其工程价值体现在三处Opus 4 的主备回退生成器、双路线一致的指数退避重试策略、以及带 Schema 校验与用量回传的结构化生成链路。对于需要在 GCP 环境内运行受控、可预测的面向客户 Agent 的团队这套适配器可以直接作为部署基线。【免费下载链接】parlantBuild reliable customer-facing AI agents with Parlant: an interaction control harness optimized for controlled, consistent, and predictable LLM interactions.项目地址: https://gitcode.com/GitHub_Trending/pa/parlant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考