Jina Gateway YAML 规范全解析：Flow 中 Gateway 配置字段与实战用法

后端微服务RPC框架模型推理服务人工智能【免费下载链接】jina☁️ Build multimodal AI applications with cloud-native stack项目地址https://gitcode.com/gh_mirrors/ji/jina点击查看免费下载导读Gateway 是 Jina Flow 的门户组件所有客户端请求都经由它进入 Flow、由它路由到各 Executor 并汇总结果返回因此它的网络协议、端口、CORS、监控、重试等配置直接决定了整个服务的对外行为。本文以仓库内 Gateway YAML 规范文档 为骨架逐字段拆解 Gateway 的 YAML 配置语义与默认值并结合 jina/serve/runtimes/gateway 源码与 tests/unit/yaml 下的真实配置样例讲解如何在 Flow YAML 中声明一个符合生产要求的 Gateway。读完你将掌握Gateway 配置的正确书写位置、全部 54 个配置字段的作用与取舍以及如何通过with块、自定义 Gateway 和运行时参数完成协议、可观测性、安全与性能调优。Gateway 在 Flow YAML 中的位置Gateway 配置必须嵌套在 Flow YAML 的gateway段下这是官方推荐且唯一的正式写法。例如定义一个使用 HTTP 协议的 Gatewayjtype: Flow version: 1 gateway: protocol: http上面的配置声明了一个对外暴露 HTTP 接口的 Gateway。除了protocolgateway段还可以放入下文 Fields 表格中的任意字段。文档明确提示虽然也可以把 Gateway 配置直接写在 Flow 顶层 with 段下但这种方式不被推荐。这一设计在仓库测试配置中得到了印证tests/unit/yaml/flow_with_gateway.yml 展示了一个双协议 自定义 Gateway的完整例子!Flow with: protocol: grpc port: 12345 gateway: py_modules: dummy_gateway.py uses: DummyGateway with: arg1: hello arg2: world protocol: http port: 12344 executors: - name: exec可以看出Flow 顶层with段的protocol/port与gateway段内的配置是独立的当两者都出现时gateway段拥有更高的针对性。而 docs/concepts/orchestration/flow.md 也给出了与 Gateway 相关的参数传播规则uses与uses_with不会被传给 Gateway但其他大多数参数会从 Flow 传播到 Gateway。不推荐写法顶层 with 段虽然 YAML 解析器见 jina/jaml/parsers/gateway/legacy.py在parse()时会兼容读取name、port、protocol、host、tracing、graph_description、graph_conditions、deployments_addresses、deployments_metadata、deployments_no_reduce、timeout_send、retries、compression、runtime_name、prefetch、log_config等顶层运行时参数官方仍建议把配置收敛到gateway:段内以免语义混淆。Gateway 配置字段全表以下字段均可在gateway段或with段中设置。表格完整继承自 docs/concepts/orchestration/gateway-args.md并按功能分组说明。基础元信息与日志NameDescriptionTypeDefaultname该对象的名称。用于 Python/YAML/CLI 中的引用、可视化、日志头等。未指定时使用默认命名策略。stringgatewayworkspace该对象任何 IO 操作的工作目录。未设置时从其父级workspace继承。stringNonelog_config该对象所用 logger 的配置名或 YAML 配置文件的绝对路径。stringdefaultquiet设置后该对象不输出任何日志。booleanFalsequiet_error设置后日志中不附带异常堆栈信息。booleanFalsetimeout_ctrl控制请求的超时时间毫秒-1 表示无限等待。number60timeout_readyPod 等待运行时就绪的超时时间毫秒-1 表示无限等待。number600000部署形态与容器NameDescriptionTypeDefaultentrypoint覆盖 Docker 镜像中 ENTRYPOINT 的入口命令未设置时使用镜像自带 ENTRYPOINT。stringNonedocker_kwargs启动 docker 容器时传给 Docker SDK 的 kwargs 参数字典详见 Docker SDK 文档。objectNonereplicasGateway 的副本数。该值仅在转换为 Kubernetes YAML 时生效。number1floating若设置当前 Pod/Deployment 不能再被继续链式追加下一次.add()会链到前一个非本 Pod/Deployment 上。booleanFalsereload若设置当 YAML 配置源发生变化时 Gateway 会在服务期间自动重启。booleanFalseenv运行时内可用的环境变量映射。objectNoneenv_from_secret从 Kubernetes 集群 Secret 读取的环境变量映射。objectNone网络协议与监听地址NameDescriptionTypeDefaultprotocolGateway 对外暴露的通信协议可取GRPC、HTTP、WEBSOCKET中的一个或多个取决于所选 Gateway 类型。array[GRPC]host运行时绑定的主机地址默认0.0.0.0。string0.0.0.0port输入数据绑定的端口。默认在[49152, 65535]范围内随机分配只使用一种协议时可传单个值使用多种协议时可传多个值。numberrandom in [49152, 65535]proxy若设置则遵循http_proxy与https_proxy环境变量否则在启动前取消这些代理变量gRPC 似乎偏好无代理环境。booleanFalsecompressionHead 向 WorkerRuntime 发送请求时使用的压缩机制详见 gRPC Python 压缩文档。stringNonegrpc_server_options启动 gRPC server 时作为 options 传入的 kwargs 字典例如{grpc.max_send_message_length: -1}。objectNone协议枚举在 jina/enums.py 中定义为ProtocolTypeGRPC 0、HTTP 1、WEBSOCKET 2并提供了from_string_list()用于把 YAML/CLI 中的字符串列表解析为枚举列表——这就是protocol字段既能接受单个字符串又能接受数组的底层原因。HTTP 服务行为FastAPI 层NameDescriptionTypeDefaulttitleHTTP 服务器的标题用于 Swagger UI 等自动生成的文档。stringNonedescriptionHTTP 服务器的描述用于 Swagger UI 等自动生成的文档。stringNonecors若设置在 FastAPI 前端添加 CORS 中间件以允许跨域访问。booleanFalseno_debug_endpoints若设置从 HTTP 接口中移除/status、/post端点。booleanFalseno_crud_endpoints若设置从 HTTP 接口中移除/index、/search、/update、/delete端点。任何绑定这些值requests(on...)的 Executor 仍会收到数据请求。booleanFalseexpose_endpoints一个 JSON 字符串表示 Executor 端点requests(on...)到 HTTP 端点的映射。stringNoneuvicorn_kwargs启动 Uvicorn 服务器时传入的 kwargs 字典详见 Uvicorn 设置文档。objectNonessl_certfile证书文件路径。stringNonessl_keyfile密钥文件路径。stringNoneexpose_graphql_endpoint若设置向 HTTP 接口添加/graphql端点。booleanFalse这些开关在源码中有精确对应HTTP 应用的构建逻辑位于 jina/serve/runtimes/gateway/http_fastapi_app.py其中cors会触发添加CORSMiddlewareno_debug_endpoints控制/status等调试端点no_crud_endpoints控制/index、/search等 CRUD 端点expose_graphql_endpoint则注册/graphql。当使用 DocArray v2 时FastAPI 应用会切换到 http_fastapi_app_docarrayv2.py 中对应实现。参数从请求处理器 request_handling.py 的_http_fastapi_default_app()一路透传到get_fastapi_app()最终交给extend_rest_interface()扩展 REST 接口。请求路由、重试与流控NameDescriptionTypeDefaultprefetch从客户端预取并送入第一个 Executor 的请求数量用于控制数据进入 Flow 的速度0表示禁用预取默认 1000 个请求。number1000retries每次 gRPC 调用的重试次数。若0则默认取max(3, num_replicas)。number-1timeout_send向 Executor 发送数据请求的超时时间毫秒-1 表示无超时默认禁用。numberNonegraph_descriptionGateway 的路由图JSON 字符串。string{}graph_conditions字典JSON 字符串说明图中每个 Executor 接收 Documents 需要满足的过滤条件。string{}deployments_addresses每个 Deployment 输入地址的 JSON 字典。string{}deployments_metadata每个 Deployment 请求元数据的 JSON 字典。string{}deployments_no_reduceJSON 列表禁用列表中每个 Deployment 的内建合并机制。string[]runtime_cls在 Pod 内运行的运行时类。stringGatewayRuntime在 request_handling.py 的初始化逻辑中graph_description、graph_conditions、deployments_no_reduce均通过json.loads()解析后交给GatewayStreamerstreamer.py 中的GatewayStreamer类retries与prefetch同样作为runtime_args传入流式管道共同决定请求在 Flow 图中的分发方式、并发窗口与失败重试策略。可观测性监控与链路追踪NameDescriptionTypeDefaultmonitoring若设置启动一个带 Prometheus 端点的 HTTP 服务器以暴露指标。booleanFalseport_monitoringPrometheus 服务器暴露的端口默认在[49152, 65535]内随机分配。numberrandom in [49152, 65535]tracing若设置启用 OpenTelemetry tracer 的 SDK 实现支持请求自动追踪与自定义 span 创建否则提供 no-op 实现。booleanFalsetraces_exporter_host启用 tracing 时用于配置 trace exporter agent 的主机名。stringNonetraces_exporter_port启用 tracing 时用于配置 trace exporter agent 的端口。numberNonemetrics若设置启用 OpenTelemetry metrics 的 SDK 实现用于默认监控与自定义测量否则提供 no-op 实现。booleanFalsemetrics_exporter_host启用 tracing 时用于配置 metrics exporter agent 的主机名。stringNonemetrics_exporter_port启用 tracing 时用于配置 metrics exporter agent 的端口。numberNone监控端点的启动逻辑位于 jina/serve/runtimes/servers/init.py 的BaseServer中_setup_monitoring()会根据monitoring与port_monitoring两个 runtime 参数决定是否拉起 Prometheus 指标服务器。自定义 Gateway 与状态能力NameDescriptionTypeDefaultusesGateway 的配置可以是一个 Gateway 类名字符串、一个 Gateway YAML 文件.yml/.yaml/.jaml、一个 Docker 镜像必须以docker://开头、一段 YAML 配置字符串必须以!或jtype:开头或 JSON 配置字符串。在 Python 中使用时还可传入代表配置的 dict、或带有.read()接口的文本文件流。stringNoneuses_with覆盖uses中with配置的关键字参数字典。objectNonepy_modules加载 Gateway 前需要导入的自定义 Python 模块。推荐只导入单个模块单文件 Gateway 可用一个简单的.py文件多文件场景应组织成包含__init__.py的 Python 包。arrayNonestateful若设置启动共识模块确保写操作在全部副本之间正确复制。booleanFalsepod_ports使用 StatefulExecutors 时重启需要保持 RAFT 集群配置的端口。numberNone自定义 Gateway 的基类定义在 jina/serve/runtimes/gateway/gateway.pyBaseGateway是所有自定义 Gateway 的基类负责与 Flow 逻辑对接Gateway则是继承BaseServer与BaseGateway的标准实现推荐在需要自定义时继承它。stateful相关能力在 Executor 侧体现为 jina/serve/executors/run.py 中的run_stateful()——它会为容器内启动一个额外的 RAFT 共识进程使用 jina/serve/consensus 目录下基于 Go 的 jraft 实现保证有状态 Executor 副本间写操作的复制一致性pod_ports正是为了在 StatefulExecutor 重启时维持 RAFT 集群配置而保留的端口。实战示例从最简单到生产级配置最小配置仅指定协议jtype: Flow version: 1 gateway: protocol: http等价于文档中的规范示例Gateway 使用 HTTP 协议端口默认在[49152, 65535]间随机分配。若省略gateway段Flow 会创建一个默认的 gRPC Gateway——这一点与protocol字段的默认值[GRPC]一致也与 tests/unit/yaml/test-http-gateway.yml 中通过!HTTPGateway显式声明 HTTP Gateway 的测试用法相呼应。HTTP Gateway 与自定义元信息参考 tests/unit/yaml/test-http-gateway.yml!HTTPGateway with: cors: true title: my-gateway-title description: my-gateway-description这份测试配置展示了 HTTP 形态 Gateway 的三个典型开关开启cors允许浏览器跨域调用title与description会出现在自动生成的 Swagger UI 文档中。多协议 Gateway由于protocol是数组类型可以同时暴露多种协议前提是所选 Gateway 支持jtype: Flow version: 1 gateway: protocol: [grpc, http, websocket] port: [12345, 12346, 12347]当使用多种协议时port也需提供对应数量的端口值。这与 tests/integration/multiple_protocol_gateway 与 tests/docker_compose/multiprotocol-gateway 等集成测试覆盖的场景一致。自定义 Gateway 类结合 tests/unit/yaml/flow_with_gateway.yml 的用法jtype: Flow version: 1 gateway: py_modules: my_gateway.py uses: MyGateway with: arg1: hello arg2: world protocol: http port: 8080 executors: - name: execpy_modules指向包含自定义 Gateway 类的 Python 文件多文件时指向包含__init__.py的包uses指定类名也可换用docker://镜像、YAML 文件或jtype:字符串with内的键值对会作为 kwargs 传入自定义 Gateway 的构造器。从解析器实现看legacy.py 的parse()会从 YAML 数据中提取name、port、protocol、host、graph_description等字段合并进runtime_args再将with段整体作为 kwargs 实例化 Gateway同时强制绑定GatewayRequestHandler作为默认请求处理器。这也解释了为什么with段能够承载任意自定义参数。配置生效链路从 YAML 到运行时完整理解 Gateway 配置还需要知道它如何被加载Schema 校验Flow/Gateway 的合法字段由 jina/schemas/gateway.py 中的schema_gateway定义。它通过_cli_to_schema(api_to_dict(), [gateway], allow_additionFalse)从 CLI 参数字典生成allow_additionFalse意味着字段白名单之外的键会被拒绝——这是可配置项以表格为准的底层约束。Schema 的描述明确指出A Gateway is a pod that encapsulates Flow logic and exposes services to the internet.JAML 解析Gateway 的 YAML 语法版本解析器位于 jina/jaml/parsers/gatewaylegacy.py负责兼容处理并把with段与 runtime 参数合并。运行时消费Gateway 继承自BaseServer与BaseGateway负责启动协议服务器request_handling.py 中的GatewayRequestHandler读取runtime_args中的图描述、重试、预取等参数构建GatewayStreamer与连接池HTTP 形态再叠加 http_fastapi_app.py 中的 FastAPI 应用层端点开关、CORS、GraphQL 均在此实现。整个链路保证了 YAML 中声明的每个字段都能精确映射到实际网络行为protocol/port/host决定监听方式prefetch/retries/timeout_send决定吞吐与容错cors/no_debug_endpoints/expose_graphql_endpoint决定 HTTP 暴露面monitoring/tracing决定可观测性stateful/pod_ports决定有状态一致性。相关文档与进一步阅读Gateway 概念与 Python 侧Flow.config_gateway()用法docs/concepts/serving/gateway/index.mdFlow 整体配置字段含参数向 Gateway 传播的规则docs/concepts/orchestration/flow.md 与 gateway-args.md其他组件的 YAML 规范docs/concepts/orchestration/yaml-spec.md可运行的真实配置样例tests/unit/yaml/flow_with_gateway.yml、tests/unit/yaml/test-http-gateway.yml多协议/自定义 Gateway 集成测试tests/integration/multiple_protocol_gateway、tests/docker_compose/multiprotocol-gateway赞分享后端微服务RPC框架模型推理服务人工智能【免费下载链接】jina☁️ Build multimodal AI applications with cloud-native stack项目地址https://gitcode.com/gh_mirrors/ji/jina点击查看免费下载相关推荐Jina YAML 规范全解析从 Executor、Flow、Gateway 到 JCloud 的完整配置指南Jina YAML 规范全解析从 Executor、Flow、Gateway 到 JCloud 的完整配置指南 YAML 是 JinaJina serve后端微服务RPC框架模型推理服务人工智能Jina YAML 规范yaml-spec全解Flow 与 Deployment 配置、IDE 校验与变量替换Jina YAML 规范yaml spec全解Flow 与 Deployment 配置、IDE 校验与变量替换 Jina 是构建多模态 AI 应用的云原生后端微服务RPC框架模型推理服务人工智能Jina Gateway 参数完全指南从 CLI、YAML 到 Python 的全量配置解析Jina Gateway 参数完全指南从 CLI、YAML 到 Python 的全量配置解析 Jina 的 Gateway 是暴露在互联网侧、封装整个 Flo后端微服务RPC框架模型推理服务人工智能上一篇实战指南如何用PingFangSC字体包打造完美跨平台字体一致性体验下一篇ChatTTS-ui离线工作模式无网络环境下的语音合成方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考