LiteLLM 接入 Arize Phoenix 提示词管理prompt_id 驱动的模板渲染与参数回注实战【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm本文以 LiteLLM 的 Arize Phoenix Prompt Management 集成为主线讲清楚如何在litellm.completion中用prompt_idprompt_variables直接消费 Phoenix 工作区里的提示词版本并深入到litellm/integrations/arize/的源码解析模板拉取、Jinja2 沙箱渲染、消息合并与元数据参数回注的完整链路帮助你在生产网关中安全地托管和热更新提示词。1. 集成概览Phoenix 提示词版本如何进入 LiteLLM该集成让 LiteLLM 的 completion 能力直接读取 Arize Phoenix从 Arize Phoenix API 拉取 prompt version通过 Phoenix 的 workspace 权限体系做访问控制LiteLLM 侧不额外鉴权401/403 由 Phoenix 返回Mustache/Handlebars 风格变量模板{{variable}}多消息 chat 模板system/user 多轮结构从 prompt 元数据自动回填模型与调用参数OpenAI / Anthropic 两套 provider 参数与调用方传入的messages合并。从源码结构看整个能力由 arize_phoenix_prompt_manager.py 中的两个类承担ArizePhoenixTemplateManager拉取 渲染和ArizePhoenixPromptManager实现 LiteLLM 提示词管理基类接口。底层 HTTP 交互由 arize_phoenix_client.py 的ArizePhoenixClient完成。注意区分同一目录下的 arize_phoenix.py 是另一套能力——把 LiteLLM 的 trace 通过 OpenTelemetry 上报到 Phoenix 的arize_phoenixsuccess_callback可参考 tests/local_testing/test_arize_phoenix.py。本文聚焦提示词管理集成即 README 的主题。2. 配置api_key 与 api_base 的取值规则在应用侧配置 Phoenix 访问凭据README 原文import litellm # Configure Arize Phoenix access # api_base should include your workspace, e.g., https://app.phoenix.arize.com/s/your-workspace/v1 api_key your-arize-phoenix-token api_base https://app.phoenix.arize.com/s/krrishdholakia/v1三个关键取值约定api_base 必须带 workspace 路径且以/v1结尾例如https://app.phoenix.arize.com/s/{workspace}/v1api_key 是 Phoenix 的 Bearer token。从init.py 的prompt_initializer可以看到它优先取litellm_params.api_key取不到时回退到环境变量PHOENIX_API_KEYapi_key: Final getattr(litellm_params, api_key, None) or os.environ.get(PHOENIX_API_KEY) api_base: Final getattr(litellm_params, api_base, None) prompt_id: Final getattr(litellm_params, prompt_id, None) if not api_key or not api_base: raise ValueError(api_key and api_base are required for Arize Phoenix prompt integration)也就是说api_base没有任何环境变量兜底必须在请求参数或 proxy 配置里显式给出api_key/api_base/prompt_id会从litellm_params中剥离后再把其余字段透传给ArizePhoenixPromptManager所以像ignore_prompt_manager_model之类的开关可以随参数一路传下去。该 initializer 通过prompt_initializer_registry以arize_phoenix键注册见 init_prompts.py 中ARIZE_PHOENIX arize_phoenix这也是 model 前缀arize/被路由到本集成的依据ArizePhoenixPromptManager.integration_name返回arize。3. 用法三种调用姿势3.1 通过 completion 使用 prompt_idimport litellm # Use with completion response litellm.completion( modelarize/gpt-4o, prompt_idUHJvbXB0VmVyc2lvbjox, # Your prompt version ID prompt_variables{question: What is artificial intelligence?}, api_keyyour-arize-phoenix-token, api_basehttps://app.phoenix.arize.com/s/krrishdholakia/v1, ) print(response.choices[0].message.content)3.2 与额外 messages 合并提示词模板渲染出的消息会前置到调用方传入的messages之前对应源码pre_call_hook中final_messages rendered_messages messages见 arize_phoenix_prompt_manager.py#L340-L344response litellm.completion( modelarize/gpt-4o, prompt_idUHJvbXB0VmVyc2lvbjox, prompt_variables{question: Explain quantum computing}, api_keyyour-arize-phoenix-token, api_basehttps://app.phoenix.arize.com/s/krrishdholakia/v1, messages[ {role: user, content: Please keep your response under 100 words.} ], )典型用法即模板提供 system 人设 第一个 user 问题messages追加约束或后续轮次。3.3 直接使用 Manager不经过 completion也可以拿渲染结果和元数据from litellm.integrations.arize.arize_phoenix_prompt_manager import ArizePhoenixPromptManager # Initialize the manager manager ArizePhoenixPromptManager( api_keyyour-arize-phoenix-token, api_basehttps://app.phoenix.arize.com/s/krrishdholakia/v1, prompt_idUHJvbXB0VmVyc2lvbjox, ) # Get rendered messages messages, metadata manager.get_prompt_template( prompt_idUHJvbXB0VmVyc2lvbjox, prompt_variables{question: What is machine learning?} ) print(Rendered messages:, messages) print(Metadata:, metadata)get_prompt_template返回的metadata会包含model、temperature、max_tokens并展开 provider 参数中尚未出现的键如top_p、frequency_penalty、presence_penalty逻辑见 arize_phoenix_prompt_manager.py#L296-L317。4. Phoenix 提示词格式与变量替换Phoenix 提示词版本的 JSON 结构README 原文示例{ data: { description: A chatbot prompt, model_provider: OPENAI, model_name: gpt-4o, template: { type: chat, messages: [ { role: system, content: [ {type: text, text: You are a chatbot} ] }, { role: user, content: [ {type: text, text: {{question}}} ] } ] }, template_type: CHAT, template_format: MUSTACHE, invocation_parameters: { type: openai, openai: {temperature: 1.0} }, id: UHJvbXB0VmVyc2lvbjox } }对照 _parse_prompt_data 的解析逻辑content是分片数组渲染时只处理type text的 part多个 text part 用空格 join 成最终字符串L186-L208invocation_parameters优先取openai键其次anthropic都没有则取第一个 dict 型嵌套值——这解释了 README 宣称的 “OpenAI and Anthropic provider parameter support”解析出的temperature/max_tokens会被提升进 metadata供pre_call_hook/_compile_prompt_helper回注到请求参数。变量替换使用 Mustache 语法Template: Hello {{name}}, your order {{order_id}} is ready! Variables: {name: Alice, order_id: 12345} Result: Hello Alice, your order 12345 is ready!4.1 源码级要点Jinja2 沙箱渲染虽然对外承诺的是 Mustache 风格实际渲染引擎是 Jinja2且刻意使用了ImmutableSandboxedEnvironmentL107-L117self.jinja_env ImmutableSandboxedEnvironment( loaderDictLoader({}), autoescapeselect_autoescape([html, xml]), # Use Mustache/Handlebars-style delimiters variable_start_string{{, variable_end_string}}, ... )源码注释解释得很直接模板来自外部 workspace 用户普通Environment()下恶意模板可能通过__class__.__init__.__globals__之类的属性遍历在代理主机上执行任意代码沙箱环境正好阻断这类遍历同时保留正常的{{ var }}替换。这一点有专门的回归测试锁定tests/test_litellm/integrations/test_prompt_manager_ssti.py 断言 Arize 管理器的jinja_env必须是ImmutableSandboxedEnvironment多个经典 SSTI 载荷渲染时抛出SecurityError而Hello {{ name }}这类正常替换保持可用。对自托管代理而言这意味着 Phoenix 工作区成员可编辑提示词但无法借此在 LiteLLM 进程内执行代码。5. 客户端实现细节请求路径、安全清洗与错误语义ArizePhoenixClient 的关键行为构造时api_key与api_base缺一不可均会抛ValueError请求头固定为Authorization: Bearer {api_key}Accept: application/jsonget_prompt_version(prompt_version_id)拼接为{api_base}/v1/prompt_versions/{safe_id}注意 client 会在 api_base 之后再补一段/v1与 api_base 本身以/v1结尾的约定组合出完整 URL返回体取data字段404 时返回None上层会包装成 “Prompt version not found” 类异常。5.1 路径穿越防护_sanitize_id 对 prompt id 做了严格清洗def _sanitize_id(identifier: str) - str: Reject path traversal characters and URL-encode the identifier. if any(c in identifier for c in (/, \\, #, ?)): raise ValueError(fInvalid identifier {identifier!r}: contains disallowed characters) if .. in identifier: raise ValueError(fInvalid identifier {identifier!r}: path traversal detected) return urllib.parse.quote(identifier, safe)即 id 中不允许出现/、\、#、?与..最终还会被 URL 编码。这意味着 README 示例中的UHJvbXB0VmVyc2lvbjoxBase64 风格的 Phoenix prompt version id是合法输入而任何试图把 id 当作路径前缀/查询串的输入都会直接报错。5.2 错误码与处理README 的错误处理约定与 get_prompt_version 的 except 分支 一一对应状态码含义客户端行为404Prompt version 不存在返回None上层抛出 “not found” 类异常401认证失败抛异常检查 access token403无权限抛异常检查 workspace 权限其他未知错误原样包装抛出使用侧的捕获示例README 原文try: response litellm.completion( modelarize/gpt-4o, prompt_idinvalid-id, arize_configarize_config, ) except Exception as e: print(fError: {e})另外注意ArizePhoenixPromptManager.pre_call_hook的设计渲染/拉取失败时只记verbose_proxy_logger.error并原样返回传入的 messages 和 paramsL367-L372即旧版 hook 路径下提示词故障不会阻断 LLM 调用而新的_compile_prompt_helper路径should_run_prompt_management在prompt_id存在时返回 True则会把编译失败包装为ValueError抛出。两种路径的取舍取决于你走哪套提示词管理入口排查问题时值得先确认。6. API 参考ArizePhoenixPromptManager提示词管理主类实现PromptManagementBase接口。README 列出的方法与源码对应get_prompt_template(prompt_id, prompt_variables)— 渲染模板返回(messages, metadata)get_available_prompts()— 列出当前已加载的 prompt ID转发给list_templatesreload_prompts()— 置空内部 manager 触发重新拉取pre_call_hook(...)— 旧式调用前置钩子渲染并前置消息、按 metadata 回注model/temperature/max_tokens/top_p/frequency_penalty/presence_penaltyget_chat_completion_prompt(...)— 委托基类完成model, messages, non_default_params的最终组装支持ignore_prompt_manager_model、ignore_prompt_manager_optional_params两个开关用于禁止模板元数据覆盖调用方显式参数。ArizePhoenixClientget_prompt_version(prompt_version_id)— 拉取单个 prompt version含 401/403/404 分支test_connection()— 访问{api_base}/prompt_versions探活成功返回True异常返回Falseclose()— 关闭底层 HTTPHandler 释放连接。7. 获取 Prompt Version ID 与 api_base操作步骤README 原文登录 Arize Phoenix进入你的 workspace打开 Prompts 分区选择一个 prompt versionID 在 URL 中/s/{workspace}/v1/prompt_versions/{PROMPT_VERSION_ID}。对应地api_base应为https://app.phoenix.arize.com/s/{workspace}/v1。例如Workspace:krrishdholakiaAPI Base:https://app.phoenix.arize.com/s/krrishdholakia/v1Prompt Version ID:UHJvbXB0VmVyc2lvbjox也可以直接用 curl 验证凭据与 IDREADME 原文命令curl -L -X GET https://app.phoenix.arize.com/s/krrishdholakia/v1/prompt_versions/UHJvbXB0VmVyc2lvbjox \ -H Authorization: Bearer YOUR_TOKEN8. 验证与测试入口tests/local_testing/test_arize_phoenix.py —arize_phoenixtrace 回调的本地联调测试需.env凭据属于 live 测试tests/test_litellm/integrations/test_prompt_manager_ssti.py — 无网络单测锁定 Arize 模板渲染器的沙箱行为可本地直接运行tests/test_litellm/integrations/arize/test_arize_phoenix.py —ArizePhoenixConfig的项目名解析、OTLP HTTP/gRPC endpoint 选择等单测。9. 小结把 Phoenix 作为 LiteLLM 的提示词后端核心就四件事配好api_base含 workspace、以/v1结尾与 Bearer token用modelarize/{model}prompt_idprompt_variables发起调用理解模板消息会前置合并、invocation_parameters会按 OpenAI/Anthropic 优先级回注到请求参数以及在多租户场景下意识到模板渲染已经过 Jinja2 沙箱与 id 路径穿越清洗。需要覆盖调用方显式参数时用ignore_prompt_manager_model/ignore_prompt_manager_optional_params两个开关即可。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考