尧图网页设计 
Plano 配置参考详解 plano_config.yml 完整字段与网关行为控制【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano本指南是 Plano 网关单实例配置文件plano_config.yml的完整参考手册覆盖模型提供商model_providers与上游请求头配置、prompt_targets 路由目标、guardrails 护栏、代理可观测性等全部能力开关。读完本文你将掌握每个顶级配置块的字段含义、取值范围、默认值及其底层实现逻辑能够独立编写一份可运行的生产级 Plano 配置文件并理解配置如何驱动 LLM 路由、Agent 编排与追踪导出。配置总览一份文件控制整个数据平面plano_config.yml是 Plano 网关AI-native proxy server 与 agentic apps 数据平面的核心配置文件它决定了一次请求从监听端口进入后如何被路由到上游 LLM 提供商、如何命中 prompt_targets、如何经过 filter 与 guardrail 链以及最终如何被追踪与计费。与配置直接对应的 JSON Schema 位于 config/plano_config_schema.yamlSchema 中明确要求顶级必须包含version与listeners两个字段其余均为可选。version字段的可选枚举值为v0.1、v0.1.0、0.1-beta、0.2.0、v0.3.0、v0.4.0参考配置文件当前使用v0.4.0version: v0.4.0一个典型的最小配置由以下几大块构成外部 Agent 注册agents、MCP 过滤器filters、LLM 提供商model_providers、HTTP 监听器listeners、可复用端点endpoints、提示词目标prompt_targets以及可选的路由偏好、限流、状态存储、护栏与追踪配置。下面按功能逐一展开。model_providers上游 LLM 提供商与请求头配置model_providers旧版别名为llm_providers仅作向后兼容保留是配置中的核心块每个条目声明一个可被路由到的上游模型。源码中对应的结构体为LlmProvider定义在 crates/common/src/configuration.rs包含name、provider_interface、access_key、model、default、passthrough_auth、headers等字段。headers附加到上游请求的 HTTP 头每个model_providers条目都可以携带一个headers映射用于向 Plano 转发到上游 LLM 的请求中追加额外的 HTTP 请求头。类型字符串映射header 名 → 值可选性可选常见用途某些 API 强制要求的User-Agent值、组织organization或账户account标识符以及其他上游服务期望携带的元数据请求头需要特别强调的是执行顺序Plano 会先根据access_key或passthrough_auth设置认证信息之后才应用headers中的追加头。这意味着你可以在headers中提供提供商相关的元数据而不会覆盖已配置的凭据。源码中该字段类型为OptionHashMapString, String见 crates/common/src/configuration.rs即任意数量的键值对都受支持。原文档给出的标准示例——为 MoonshotAI 的 Kimi for Coding 配置User-Agentmodel_providers: - model: moonshotai/kimi-for-coding access_key: $MOONSHOTAI_API_KEY base_url: https://api.kimi.com/coding/v1 headers: User-Agent: KimiCLI/1.3access_key支持$ENV_VAR形式的环境变量引用密钥本身不直接写死在配置文件中。而base_url则用于覆盖该模型的默认服务地址适合接入兼容 OpenAI 协议的自建网关或第三方中转。其他提供商级字段在完整参考配置文件 docs/source/resources/includes/plano_config_full_reference.yaml 中一个提供商条目可以组合使用以下字段字段说明示例值model完整模型名provider/modelopenai/gpt-4oaccess_keyAPI 密钥支持$ENV_VAR$OPENAI_API_KEYdefault是否为默认模型未显式指定时兜底truebase_url覆盖上游服务地址https://litellm.example.compassthrough_auth透传客户端Authorization头而非使用access_keytruehttp_host显式覆盖上游Host头api.custom-provider.comheaders附加请求头认证之后应用User-Agent: KimiCLI/1.3provider_interface上游协议接口openai、anthropic、gemini等其中passthrough_auth特别适合 LiteLLM 这类代理场景——由 LiteLLM 自行校验虚拟密钥Plano 只负责把客户端的认证头原样转发参考配置中对应的示例为- model: openai/gpt-4o-litellm base_url: https://litellm.example.com passthrough_auth: truehttp_host则用于自定义或自托管端点当上游要求Host头与地址分离时使用- model: openai/llama-3.3-70b base_url: https://api.custom-provider.com http_host: api.custom-provider.com access_key: $CUSTOM_API_KEYSchema 中provider_interface的枚举值包括plano、deepseek、groq、mistral、openai、xiaomi、gemini、chatgpt、digitalocean、vercel、openrouter、edenai、moonshotai见 config/plano_config_schema.yaml覆盖了绝大多数主流模型服务商。此外旧版将routing_preferences内联在提供商条目下的写法已标记为 DEPRECATED配置生成器会自动将其迁移到顶级routing_preferences列表新配置应直接在顶层声明。model_aliases友好名称替代完整模型名model_aliases允许为常用模型定义简短别名客户端在请求中可直接使用别名而非完整 provider/model 名称model_aliases: fast-llm: target: gpt-4o-mini smart-llm: target: gpt-4oSchema 要求每个别名条目必须包含target字段config/plano_config_schema.yaml。别名机制让上层应用与底层模型选择解耦——调整模型时只需修改配置中的target无需改动客户端代码。routing_preferences 与 model_metrics_sources意图驱动的智能模型路由routing_preferences是顶层列表将命名任务类别与一组有序的候选模型池绑定。Plano 的 LLM 路由器会把入站请求与这些描述进行语义匹配返回一个有序模型列表客户端以models[0]为主模型在遇到 429/5xx 时依次用models[1]、models[2]重试。routing_preferences: - name: code generation description: generating new code snippets, functions, or boilerplate based on user prompts or requirements models: - anthropic/claude-sonnet-4-0 - openai/gpt-4o - groq/llama-3.3-70b-versatile - name: code review description: reviewing, analyzing, and suggesting improvements to existing code models: - anthropic/claude-sonnet-4-0 - groq/llama-3.3-70b-versatile selection_policy: prefer: cheapest使用routing_preferences有两个前置条件每个models中的模型必须已在model_providers中声明overrides.llm_routing_model必须指向 Plano-Orchestrator或同等能力的路由模型。selection_policy.prefer是可选字段取值为cheapest、fastest或none默认。设置后路由器会利用来自model_metrics_sources的实时成本/延迟数据对候选模型重新排序。model_metrics_sources声明路由器读取的外部目录用于支持selection_policymodel_metrics_sources: - type: cost provider: models.dev url: https://models.dev/api.json # optional; omit to use the provider default refresh_interval: 3600 # optional, seconds model_aliases: # optional: catalog key - Plano model name openai/gpt-oss-120b: openai/gpt-4o - type: latency provider: prometheus url: http://prometheus:9090 query: avg by (model_name) (rate(plano_llm_latency_seconds_sum[5m])) refresh_interval: 60cost类型的数据源支持models.dev与digitalocean两种 provider不写url时使用各自默认目录用于支撑prefer: cheapest的排序latency类型使用 Prometheus 查询用于支撑prefer: fastest。refresh_interval控制目录刷新周期model_aliases用于把目录中的 key 映射到 Plano 侧模型名例如openai/gpt-oss-120b→openai/gpt-4o。listeners网关的三种流量入口listeners是配置中除version外的另一个必填块定义了网关对外暴露的监听端口。Schema 支持三种typemodel、prompt、agent且提供旧版ingress_traffic/egress_traffic对象格式的兼容已弃用建议使用列表格式。agent 监听器多 Agent 请求路由- type: agent name: travel_booking_service port: 8001 router: plano_orchestrator_v1 address: 0.0.0.0 agents: - id: rag_agent description: virtual assistant for retrieval augmented generation tasks input_filters: - input_guardsrouter指定使用的编排器当前枚举值为plano_orchestrator_v1每个子 agent 条目包含id、description供编排器做语义选择、可选default标记与input_filters列表。API 类型由请求路径控制/v1/responses、/v1/messages、/v1/chat/completions。model 监听器直接 LLM 访问- type: model name: model_1 address: 0.0.0.0 port: 12000 timeout: 30s # Request timeout (e.g. 30s, 60s) max_retries: 3 # Number of retries on upstream failure input_filters: # Filters applied before forwarding to LLM - input_guards output_filters: # Filters applied to LLM responses before returning to client - input_guardstimeout控制请求超时字符串形式如30s、60smax_retries控制上游失败时的重试次数input_filters/output_filters分别在转发前与返回前应用过滤器。prompt 监听器函数调用入口- type: prompt name: prompt_function_listener address: 0.0.0.0 port: 10000prompt 监听器为prompt_targets提供函数调用能力入口。endpoints可复用的服务端点endpoints定义可被prompt_targets引用的后端服务地址通过名称复用避免重复书写连接参数endpoints: app_server: endpoint: 127.0.0.1:80 connect_timeout: 0.005s protocol: http # http or https mistral_local: endpoint: 127.0.0.1:8001 secure_service: endpoint: api.example.com:443 protocol: https http_host: api.example.com # Override the Host header sent upstream字段说明endpoint必填服务地址host:portprotocolhttp或https默认按端口推断connect_timeout连接超时如0.005shttp_host显式覆盖发送给上游的Host头prefix_affinitySchema 中额外定义针对 vLLM 等多副本自托管后端按x-plano-prefix-hash头做一致性哈希使相同 prompt 前缀始终命中同一副本以复用其 KV cache默认falseprompt_targets函数调用与 API 编排的目标prompt_targets定义可供 LLM 调用的函数function calling目标。每个目标声明参数 Schema、后端端点以及可选的目标级系统提示词prompt_targets: - name: get_current_weather description: Get current weather at a location. parameters: - name: location description: The location to get the weather for required: true type: string format: City, State - name: days description: the number of days for the request required: true type: int endpoint: name: app_server path: /weather http_method: POST system_prompt: You are a weather expert. Provide accurate and concise weather information. auto_llm_dispatch_on_response: true关键字段parameters每个参数包含name、description、type、required、可选的format、enum、default、in_pathSchema 中定义控制参数是否放入路径endpoint引用endpoints中定义的name配合path与http_methodGET/POST可选http_headers附加请求头system_prompt目标级系统提示词覆盖顶层system_promptauto_llm_dispatch_on_response为true时LLM 会携带函数调用返回结果再次被调用以生成面向用户的最终自然语言回答形成完整的工具调用闭环顶层的system_prompt作为默认系统提示词对所有未单独配置的prompt_targets生效system_prompt: | You are a helpful assistant. Always respond concisely and accurately.agents 与 filters外部 Agent 与 MCP 过滤器agents注册外部 HTTP Agent 服务供 agent 监听器路由使用agents: - id: weather_agent # Example agent for weather url: http://localhost:10510 - id: flight_agent # Example agent for flights url: http://localhost:10520filters注册应用于请求/响应的 MCP 过滤器输入校验、查询重写等filters: - id: input_guards # Example filter for input validation url: http://localhost:10500 # type: mcp (default) # transport: streamable-http (default) # tool: input_guards (default - same as filter id)Schema 表明type可选mcp或http默认mcptransport当前支持streamable-httptool默认与 filter 的id相同。过滤器通过在监听器或 agent 条目中引用id挂载到请求链路。ratelimits按模型与选择器的令牌限流ratelimits按「模型 选择器」维度控制令牌用量。selector通过 HTTP 请求头识别限流主体limit声明时间单位内的最大令牌数ratelimits: - model: openai/gpt-4o selector: key: x-user-id # HTTP header key used to identify the rate-limit subject value: * # Wildcard matches any value; use a specific string to target one limit: tokens: 100000 # Maximum tokens allowed in the given time unit unit: hour # Time unit: minute, hour, or day - model: openai/gpt-4o-mini selector: key: x-org-id value: acme-corp limit: tokens: 500000 unit: dayselector.value支持通配符*匹配任意值或精确字符串仅限特定主体unit的合法取值为minute、hour、day。overrides全局行为覆盖overrides控制网关级全局行为参考配置中列出的字段及含义如下overrides: prompt_target_intent_matching_threshold: 0.7 optimize_context_window: true use_agent_orchestrator: false upstream_connect_timeout: 10s upstream_tls_ca_path: /etc/ssl/certs/ca-certificates.crt llm_routing_model: Plano-Orchestrator agent_orchestration_model: Plano-Orchestrator disable_signals: false字段说明默认值prompt_target_intent_matching_threshold将请求路由到 prompt_target 的意图匹配阈值0.0–1.0越低越宽松—optimize_context_window修剪对话历史以适配模型上下文窗口falseuse_agent_orchestrator启用多 Agent 请求编排falseupstream_connect_timeout上游提供商集群的连接超时如5s、10s5supstream_tls_ca_path上游 TLS 校验的受信 CA 包路径/etc/ssl/certs/ca-certificates.crtllm_routing_model意图型 LLM 路由所用模型必须已在 model_providers 中声明—agent_orchestration_modelAgent 编排所用模型必须已在 model_providers 中声明—disable_signals关闭 LLM 响应上的 agentic 信号分析挫败感、重复、升级等以节省 CPUfalseorchestrator_model_context_length编排/路由模型的上下文窗口最大令牌数Schema 定义8192其中disable_signals对应 Plano 的 agentic signals 能力——位于 crates/brightstaff/src/signals 下的环境信号exhaustion、执行信号failure、loops、交互信号disengagement、misalignment、satisfaction、stagnation等分析模块在不需要时可整体关闭以降低 CPU 开销。routing会话亲和与模型路由缓存routing块为 agentic 循环中的路由决策提供会话级钉扎pinning能力routing: session_ttl_seconds: 600 # How long a pinned session lasts (default: 600s / 10 min) session_max_entries: 10000 # Max cached sessions before eviction (upper limit: 10000) # route_on_user_only: true session_cache: type: memory # memory (default) or redis # url: redis://localhost:6379 # tenant_header: x-org-idsession_ttl_seconds会话钉扎的存活时长默认 600 秒10 分钟session_max_entries缓存会话上限默认 10000Schema 上限 10000route_on_user_only可选开关为true时只在最后一条消息为用户消息时执行质量路由工具结果/助手延续步骤则回放之前的决策默认falsesession_cache.typememory默认进程内适用于单实例或redis跨副本共享多副本/Kubernetes 部署必需type为redis时必须提供url支持redis://与rediss://TLS 连接tenant_header可选设置后缓存键按plano:affinity:{tenant_id}:{session_id}隔离租户Schema 中还定义了可选的routing_budget块max_switch_spend_pct必填作为会话级模型切换成本闸门把「放弃仍可能温热的 provider 缓存」所带来的输入令牌成本计入会话累计切换开销仅当该开销不超过从不切换基线成本的max_switch_spend_pct百分比时才允许付费切换0表示绝不付费切换仅允许绝对更便宜的切换。该功能独立于 prompt_caching且需要model_metrics_sources中存在 cost 数据源。客户端可通过x-plano-max-switch-spend-pct请求头按请求覆盖该百分比。state_storage多轮对话历史存储state_storage决定多轮对话状态的保存后端state_storage: type: memory # memory (in-process) or postgres (persistent) # connection_string: postgresql://user:$DB_PASSlocalhost:5432/planotypememory进程内或postgres持久化connection_stringtype为postgres时必填支持$VAR或${VAR}环境变量替换Schema 中通过allOf条件约束强制该依赖关系PostgreSQL 模式下需要预先初始化对话状态表建表 SQL 可参考 docs/source/resources/db_setup/conversation_states.sql。prompt_guards全局输入护栏prompt_guards配置全局应用的输入护栏参考配置中的jailbreak检测在命中异常时的兜底回复prompt_guards: input_guards: jailbreak: on_exception: message: Im sorry, I cant help with that request.Schema 要求input_guards下必须包含jailbreak块且on_exception.message必填。护栏可以与监听器上的input_filters/output_filters组合使用形成多层防御。tracingOpenTelemetry 追踪与 AI 可观测性导出tracing块控制链路追踪的采样、内部 span 开关、OTLP 导出目标与 span 属性tracing: random_sampling: 100 trace_arch_internal: false opentracing_grpc_endpoint: http://localhost:4317 span_attributes: header_prefixes: - x-user- - x-org- static: environment: production service.team: platform exporters: - type: posthog url: https://us.i.posthog.com api_key: $POSTHOG_API_KEY distinct_id_header: x-user-id capture_messages: falserandom_sampling随机采样百分比1–100trace_arch_internal是否在 trace 中包含 Plano 内部 spanopentracing_grpc_endpointOpenTelemetry Collector如 Jaeger、Tempo的 gRPC 端点span_attributes.header_prefixes将名称以这些前缀开头的请求头作为 span 属性传播span_attributes.static附加到每个 span 的静态键值对exporters提供商无关的导出目标LLM span 除发送到上述 gRPC 端点外还会流式发送到每个 exporter。posthog类型将每次 LLM 调用捕获为$ai_generation事件url后会自动追加/batch/采集路径api_key支持$ENV_VAR展开distinct_id_header指定用作 PostHogdistinct_id的请求头省略则匿名采集capture_messages为true时在$ai_input中包含截断后的用户消息组合示例与验证方式将上述所有块整合到一份配置中即可得到一个覆盖路由、护栏、限流、状态与追踪的完整示例即原文档引用的 docs/source/resources/includes/plano_config_full_reference.yaml本文所有示例均取自该文件建议作为编写新配置的蓝本直接对照使用。配置的合法性以 config/plano_config_schema.yaml 为权威校验标准顶级additionalProperties: false意味着未知字段会直接报错。Schema 定义与源码结构体crates/common/src/configuration.rs保持同步例如headers字段对应LlmProvider.headers: OptionHashMapString, Stringpassthrough_auth对应同名布尔字段。仓库中的config/目录还提供了 envoy.template.yaml、docker-compose.dev.yaml 与 plano_config_schema.yaml可结合本地开发环境config/docker-compose.dev.yaml进行编排启动另有 config/validate_plano_config.sh 可用于对配置文件做前置校验。在动手部署前建议先通读 docs/source/resources/deployment.rst 了解网关的部署形态再结合本文逐块编写配置最后用校验脚本与真实请求验证各监听器、路由偏好与追踪导出是否符合预期。【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Plano 配置参考：详解 plano_config.yml 完整字段与网关行为控制
Plano 配置参考详解 plano_config.yml 完整字段与网关行为控制【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano本指南是 Plano 网关单实例配置文件plano_config.yml的完整参考手册覆盖模型提供商model_providers与上游请求头配置、prompt_targets 路由目标、guardrails 护栏、代理可观测性等全部能力开关。读完本文你将掌握每个顶级配置块的字段含义、取值范围、默认值及其底层实现逻辑能够独立编写一份可运行的生产级 Plano 配置文件并理解配置如何驱动 LLM 路由、Agent 编排与追踪导出。配置总览一份文件控制整个数据平面plano_config.yml是 Plano 网关AI-native proxy server 与 agentic apps 数据平面的核心配置文件它决定了一次请求从监听端口进入后如何被路由到上游 LLM 提供商、如何命中 prompt_targets、如何经过 filter 与 guardrail 链以及最终如何被追踪与计费。与配置直接对应的 JSON Schema 位于 config/plano_config_schema.yamlSchema 中明确要求顶级必须包含version与listeners两个字段其余均为可选。version字段的可选枚举值为v0.1、v0.1.0、0.1-beta、0.2.0、v0.3.0、v0.4.0参考配置文件当前使用v0.4.0version: v0.4.0一个典型的最小配置由以下几大块构成外部 Agent 注册agents、MCP 过滤器filters、LLM 提供商model_providers、HTTP 监听器listeners、可复用端点endpoints、提示词目标prompt_targets以及可选的路由偏好、限流、状态存储、护栏与追踪配置。下面按功能逐一展开。model_providers上游 LLM 提供商与请求头配置model_providers旧版别名为llm_providers仅作向后兼容保留是配置中的核心块每个条目声明一个可被路由到的上游模型。源码中对应的结构体为LlmProvider定义在 crates/common/src/configuration.rs包含name、provider_interface、access_key、model、default、passthrough_auth、headers等字段。headers附加到上游请求的 HTTP 头每个model_providers条目都可以携带一个headers映射用于向 Plano 转发到上游 LLM 的请求中追加额外的 HTTP 请求头。类型字符串映射header 名 → 值可选性可选常见用途某些 API 强制要求的User-Agent值、组织organization或账户account标识符以及其他上游服务期望携带的元数据请求头需要特别强调的是执行顺序Plano 会先根据access_key或passthrough_auth设置认证信息之后才应用headers中的追加头。这意味着你可以在headers中提供提供商相关的元数据而不会覆盖已配置的凭据。源码中该字段类型为OptionHashMapString, String见 crates/common/src/configuration.rs即任意数量的键值对都受支持。原文档给出的标准示例——为 MoonshotAI 的 Kimi for Coding 配置User-Agentmodel_providers: - model: moonshotai/kimi-for-coding access_key: $MOONSHOTAI_API_KEY base_url: https://api.kimi.com/coding/v1 headers: User-Agent: KimiCLI/1.3access_key支持$ENV_VAR形式的环境变量引用密钥本身不直接写死在配置文件中。而base_url则用于覆盖该模型的默认服务地址适合接入兼容 OpenAI 协议的自建网关或第三方中转。其他提供商级字段在完整参考配置文件 docs/source/resources/includes/plano_config_full_reference.yaml 中一个提供商条目可以组合使用以下字段字段说明示例值model完整模型名provider/modelopenai/gpt-4oaccess_keyAPI 密钥支持$ENV_VAR$OPENAI_API_KEYdefault是否为默认模型未显式指定时兜底truebase_url覆盖上游服务地址https://litellm.example.compassthrough_auth透传客户端Authorization头而非使用access_keytruehttp_host显式覆盖上游Host头api.custom-provider.comheaders附加请求头认证之后应用User-Agent: KimiCLI/1.3provider_interface上游协议接口openai、anthropic、gemini等其中passthrough_auth特别适合 LiteLLM 这类代理场景——由 LiteLLM 自行校验虚拟密钥Plano 只负责把客户端的认证头原样转发参考配置中对应的示例为- model: openai/gpt-4o-litellm base_url: https://litellm.example.com passthrough_auth: truehttp_host则用于自定义或自托管端点当上游要求Host头与地址分离时使用- model: openai/llama-3.3-70b base_url: https://api.custom-provider.com http_host: api.custom-provider.com access_key: $CUSTOM_API_KEYSchema 中provider_interface的枚举值包括plano、deepseek、groq、mistral、openai、xiaomi、gemini、chatgpt、digitalocean、vercel、openrouter、edenai、moonshotai见 config/plano_config_schema.yaml覆盖了绝大多数主流模型服务商。此外旧版将routing_preferences内联在提供商条目下的写法已标记为 DEPRECATED配置生成器会自动将其迁移到顶级routing_preferences列表新配置应直接在顶层声明。model_aliases友好名称替代完整模型名model_aliases允许为常用模型定义简短别名客户端在请求中可直接使用别名而非完整 provider/model 名称model_aliases: fast-llm: target: gpt-4o-mini smart-llm: target: gpt-4oSchema 要求每个别名条目必须包含target字段config/plano_config_schema.yaml。别名机制让上层应用与底层模型选择解耦——调整模型时只需修改配置中的target无需改动客户端代码。routing_preferences 与 model_metrics_sources意图驱动的智能模型路由routing_preferences是顶层列表将命名任务类别与一组有序的候选模型池绑定。Plano 的 LLM 路由器会把入站请求与这些描述进行语义匹配返回一个有序模型列表客户端以models[0]为主模型在遇到 429/5xx 时依次用models[1]、models[2]重试。routing_preferences: - name: code generation description: generating new code snippets, functions, or boilerplate based on user prompts or requirements models: - anthropic/claude-sonnet-4-0 - openai/gpt-4o - groq/llama-3.3-70b-versatile - name: code review description: reviewing, analyzing, and suggesting improvements to existing code models: - anthropic/claude-sonnet-4-0 - groq/llama-3.3-70b-versatile selection_policy: prefer: cheapest使用routing_preferences有两个前置条件每个models中的模型必须已在model_providers中声明overrides.llm_routing_model必须指向 Plano-Orchestrator或同等能力的路由模型。selection_policy.prefer是可选字段取值为cheapest、fastest或none默认。设置后路由器会利用来自model_metrics_sources的实时成本/延迟数据对候选模型重新排序。model_metrics_sources声明路由器读取的外部目录用于支持selection_policymodel_metrics_sources: - type: cost provider: models.dev url: https://models.dev/api.json # optional; omit to use the provider default refresh_interval: 3600 # optional, seconds model_aliases: # optional: catalog key - Plano model name openai/gpt-oss-120b: openai/gpt-4o - type: latency provider: prometheus url: http://prometheus:9090 query: avg by (model_name) (rate(plano_llm_latency_seconds_sum[5m])) refresh_interval: 60cost类型的数据源支持models.dev与digitalocean两种 provider不写url时使用各自默认目录用于支撑prefer: cheapest的排序latency类型使用 Prometheus 查询用于支撑prefer: fastest。refresh_interval控制目录刷新周期model_aliases用于把目录中的 key 映射到 Plano 侧模型名例如openai/gpt-oss-120b→openai/gpt-4o。listeners网关的三种流量入口listeners是配置中除version外的另一个必填块定义了网关对外暴露的监听端口。Schema 支持三种typemodel、prompt、agent且提供旧版ingress_traffic/egress_traffic对象格式的兼容已弃用建议使用列表格式。agent 监听器多 Agent 请求路由- type: agent name: travel_booking_service port: 8001 router: plano_orchestrator_v1 address: 0.0.0.0 agents: - id: rag_agent description: virtual assistant for retrieval augmented generation tasks input_filters: - input_guardsrouter指定使用的编排器当前枚举值为plano_orchestrator_v1每个子 agent 条目包含id、description供编排器做语义选择、可选default标记与input_filters列表。API 类型由请求路径控制/v1/responses、/v1/messages、/v1/chat/completions。model 监听器直接 LLM 访问- type: model name: model_1 address: 0.0.0.0 port: 12000 timeout: 30s # Request timeout (e.g. 30s, 60s) max_retries: 3 # Number of retries on upstream failure input_filters: # Filters applied before forwarding to LLM - input_guards output_filters: # Filters applied to LLM responses before returning to client - input_guardstimeout控制请求超时字符串形式如30s、60smax_retries控制上游失败时的重试次数input_filters/output_filters分别在转发前与返回前应用过滤器。prompt 监听器函数调用入口- type: prompt name: prompt_function_listener address: 0.0.0.0 port: 10000prompt 监听器为prompt_targets提供函数调用能力入口。endpoints可复用的服务端点endpoints定义可被prompt_targets引用的后端服务地址通过名称复用避免重复书写连接参数endpoints: app_server: endpoint: 127.0.0.1:80 connect_timeout: 0.005s protocol: http # http or https mistral_local: endpoint: 127.0.0.1:8001 secure_service: endpoint: api.example.com:443 protocol: https http_host: api.example.com # Override the Host header sent upstream字段说明endpoint必填服务地址host:portprotocolhttp或https默认按端口推断connect_timeout连接超时如0.005shttp_host显式覆盖发送给上游的Host头prefix_affinitySchema 中额外定义针对 vLLM 等多副本自托管后端按x-plano-prefix-hash头做一致性哈希使相同 prompt 前缀始终命中同一副本以复用其 KV cache默认falseprompt_targets函数调用与 API 编排的目标prompt_targets定义可供 LLM 调用的函数function calling目标。每个目标声明参数 Schema、后端端点以及可选的目标级系统提示词prompt_targets: - name: get_current_weather description: Get current weather at a location. parameters: - name: location description: The location to get the weather for required: true type: string format: City, State - name: days description: the number of days for the request required: true type: int endpoint: name: app_server path: /weather http_method: POST system_prompt: You are a weather expert. Provide accurate and concise weather information. auto_llm_dispatch_on_response: true关键字段parameters每个参数包含name、description、type、required、可选的format、enum、default、in_pathSchema 中定义控制参数是否放入路径endpoint引用endpoints中定义的name配合path与http_methodGET/POST可选http_headers附加请求头system_prompt目标级系统提示词覆盖顶层system_promptauto_llm_dispatch_on_response为true时LLM 会携带函数调用返回结果再次被调用以生成面向用户的最终自然语言回答形成完整的工具调用闭环顶层的system_prompt作为默认系统提示词对所有未单独配置的prompt_targets生效system_prompt: | You are a helpful assistant. Always respond concisely and accurately.agents 与 filters外部 Agent 与 MCP 过滤器agents注册外部 HTTP Agent 服务供 agent 监听器路由使用agents: - id: weather_agent # Example agent for weather url: http://localhost:10510 - id: flight_agent # Example agent for flights url: http://localhost:10520filters注册应用于请求/响应的 MCP 过滤器输入校验、查询重写等filters: - id: input_guards # Example filter for input validation url: http://localhost:10500 # type: mcp (default) # transport: streamable-http (default) # tool: input_guards (default - same as filter id)Schema 表明type可选mcp或http默认mcptransport当前支持streamable-httptool默认与 filter 的id相同。过滤器通过在监听器或 agent 条目中引用id挂载到请求链路。ratelimits按模型与选择器的令牌限流ratelimits按「模型 选择器」维度控制令牌用量。selector通过 HTTP 请求头识别限流主体limit声明时间单位内的最大令牌数ratelimits: - model: openai/gpt-4o selector: key: x-user-id # HTTP header key used to identify the rate-limit subject value: * # Wildcard matches any value; use a specific string to target one limit: tokens: 100000 # Maximum tokens allowed in the given time unit unit: hour # Time unit: minute, hour, or day - model: openai/gpt-4o-mini selector: key: x-org-id value: acme-corp limit: tokens: 500000 unit: dayselector.value支持通配符*匹配任意值或精确字符串仅限特定主体unit的合法取值为minute、hour、day。overrides全局行为覆盖overrides控制网关级全局行为参考配置中列出的字段及含义如下overrides: prompt_target_intent_matching_threshold: 0.7 optimize_context_window: true use_agent_orchestrator: false upstream_connect_timeout: 10s upstream_tls_ca_path: /etc/ssl/certs/ca-certificates.crt llm_routing_model: Plano-Orchestrator agent_orchestration_model: Plano-Orchestrator disable_signals: false字段说明默认值prompt_target_intent_matching_threshold将请求路由到 prompt_target 的意图匹配阈值0.0–1.0越低越宽松—optimize_context_window修剪对话历史以适配模型上下文窗口falseuse_agent_orchestrator启用多 Agent 请求编排falseupstream_connect_timeout上游提供商集群的连接超时如5s、10s5supstream_tls_ca_path上游 TLS 校验的受信 CA 包路径/etc/ssl/certs/ca-certificates.crtllm_routing_model意图型 LLM 路由所用模型必须已在 model_providers 中声明—agent_orchestration_modelAgent 编排所用模型必须已在 model_providers 中声明—disable_signals关闭 LLM 响应上的 agentic 信号分析挫败感、重复、升级等以节省 CPUfalseorchestrator_model_context_length编排/路由模型的上下文窗口最大令牌数Schema 定义8192其中disable_signals对应 Plano 的 agentic signals 能力——位于 crates/brightstaff/src/signals 下的环境信号exhaustion、执行信号failure、loops、交互信号disengagement、misalignment、satisfaction、stagnation等分析模块在不需要时可整体关闭以降低 CPU 开销。routing会话亲和与模型路由缓存routing块为 agentic 循环中的路由决策提供会话级钉扎pinning能力routing: session_ttl_seconds: 600 # How long a pinned session lasts (default: 600s / 10 min) session_max_entries: 10000 # Max cached sessions before eviction (upper limit: 10000) # route_on_user_only: true session_cache: type: memory # memory (default) or redis # url: redis://localhost:6379 # tenant_header: x-org-idsession_ttl_seconds会话钉扎的存活时长默认 600 秒10 分钟session_max_entries缓存会话上限默认 10000Schema 上限 10000route_on_user_only可选开关为true时只在最后一条消息为用户消息时执行质量路由工具结果/助手延续步骤则回放之前的决策默认falsesession_cache.typememory默认进程内适用于单实例或redis跨副本共享多副本/Kubernetes 部署必需type为redis时必须提供url支持redis://与rediss://TLS 连接tenant_header可选设置后缓存键按plano:affinity:{tenant_id}:{session_id}隔离租户Schema 中还定义了可选的routing_budget块max_switch_spend_pct必填作为会话级模型切换成本闸门把「放弃仍可能温热的 provider 缓存」所带来的输入令牌成本计入会话累计切换开销仅当该开销不超过从不切换基线成本的max_switch_spend_pct百分比时才允许付费切换0表示绝不付费切换仅允许绝对更便宜的切换。该功能独立于 prompt_caching且需要model_metrics_sources中存在 cost 数据源。客户端可通过x-plano-max-switch-spend-pct请求头按请求覆盖该百分比。state_storage多轮对话历史存储state_storage决定多轮对话状态的保存后端state_storage: type: memory # memory (in-process) or postgres (persistent) # connection_string: postgresql://user:$DB_PASSlocalhost:5432/planotypememory进程内或postgres持久化connection_stringtype为postgres时必填支持$VAR或${VAR}环境变量替换Schema 中通过allOf条件约束强制该依赖关系PostgreSQL 模式下需要预先初始化对话状态表建表 SQL 可参考 docs/source/resources/db_setup/conversation_states.sql。prompt_guards全局输入护栏prompt_guards配置全局应用的输入护栏参考配置中的jailbreak检测在命中异常时的兜底回复prompt_guards: input_guards: jailbreak: on_exception: message: Im sorry, I cant help with that request.Schema 要求input_guards下必须包含jailbreak块且on_exception.message必填。护栏可以与监听器上的input_filters/output_filters组合使用形成多层防御。tracingOpenTelemetry 追踪与 AI 可观测性导出tracing块控制链路追踪的采样、内部 span 开关、OTLP 导出目标与 span 属性tracing: random_sampling: 100 trace_arch_internal: false opentracing_grpc_endpoint: http://localhost:4317 span_attributes: header_prefixes: - x-user- - x-org- static: environment: production service.team: platform exporters: - type: posthog url: https://us.i.posthog.com api_key: $POSTHOG_API_KEY distinct_id_header: x-user-id capture_messages: falserandom_sampling随机采样百分比1–100trace_arch_internal是否在 trace 中包含 Plano 内部 spanopentracing_grpc_endpointOpenTelemetry Collector如 Jaeger、Tempo的 gRPC 端点span_attributes.header_prefixes将名称以这些前缀开头的请求头作为 span 属性传播span_attributes.static附加到每个 span 的静态键值对exporters提供商无关的导出目标LLM span 除发送到上述 gRPC 端点外还会流式发送到每个 exporter。posthog类型将每次 LLM 调用捕获为$ai_generation事件url后会自动追加/batch/采集路径api_key支持$ENV_VAR展开distinct_id_header指定用作 PostHogdistinct_id的请求头省略则匿名采集capture_messages为true时在$ai_input中包含截断后的用户消息组合示例与验证方式将上述所有块整合到一份配置中即可得到一个覆盖路由、护栏、限流、状态与追踪的完整示例即原文档引用的 docs/source/resources/includes/plano_config_full_reference.yaml本文所有示例均取自该文件建议作为编写新配置的蓝本直接对照使用。配置的合法性以 config/plano_config_schema.yaml 为权威校验标准顶级additionalProperties: false意味着未知字段会直接报错。Schema 定义与源码结构体crates/common/src/configuration.rs保持同步例如headers字段对应LlmProvider.headers: OptionHashMapString, Stringpassthrough_auth对应同名布尔字段。仓库中的config/目录还提供了 envoy.template.yaml、docker-compose.dev.yaml 与 plano_config_schema.yaml可结合本地开发环境config/docker-compose.dev.yaml进行编排启动另有 config/validate_plano_config.sh 可用于对配置文件做前置校验。在动手部署前建议先通读 docs/source/resources/deployment.rst 了解网关的部署形态再结合本文逐块编写配置最后用校验脚本与真实请求验证各监听器、路由偏好与追踪导出是否符合预期。【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考