AIBrix 本地模式Local Mode实战指南无 Docker/Kubernetes 运行 Envoy 与 gateway-plugin 双进程网关【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix导读AIBrix 本地模式Local Mode将 AIBrix 网关拆解为 Envoy 与 gateway-plugin 两个裸进程通过静态配置直接发现 vLLM 推理引擎无需 Docker 容器与 Kubernetes 集群即可运行。本文以 deployment/local/README.md 为骨架结合仓库内启动脚本、Envoy 配置与路由算法源码完整讲解本地模式的架构原理、环境准备、启动停止、配置项与排障方法帮助你在单机环境快速调试 AIBrix 的路由与网关行为。本地模式是什么适用场景与能力边界本地模式的核心思想是去掉一切容器与编排依赖只保留网关本身。它以两个原生二进制进程运行Envoy负责接收 HTTP 请求并通过 ext_proc 外部处理过滤器与插件通信最终把请求路由到选定的后端gateway-plugin以--standalone模式运行从静态endpoints.yaml中读取 vLLM 后端地址用配置的路由算法选出最佳后端并返回给 Envoy。这一模式最典型的适用场景是本地开发与调试路由算法无需每次改动都重新构建镜像、拉起 Pod单节点测试避免容器与编排层的额外开销快速验证网关行为路由选择、请求转发、健康检查等。需要注意的能力边界本地模式不包含 AIBrix controller 的编排能力。原文档明确提示Local Mode does not include AIBrix controller orchestration, they can not run without Kubernetes——即 PodAutoscaler、ModelAdapter、KV Cache 等由 controller 管理的编排逻辑依赖 Kubernetes在本地模式下不会生效。架构与请求流转ext_proc target-pod ORIGINAL_DST本地模式的整体请求链路如下源自 deployment/local/README.md 的架构图┌────────────────────────┐ curl :10080 │ gateway-plugin │ │ │ (gRPC :50052) │ ▼ │ │ ┌─────────────┐ ext_proc gRPC │ --standalone │ │ Envoy │ ───────────────► │ --endpoints-config │ │ (:10080) │ │ │ │ │ ◄─ target-pod ── │ selects best backend │ │ ORIGINAL │ header └────────────────────────┘ │ _DST │ │ cluster │ ──── route to ──► vLLM engine(s) └─────────────┘ selected IP (e.g., 127.0.0.1:8000)完整流转过程为客户端向 Envoy 的 10080 端口发送 HTTP 请求 → Envoy 通过 ext_proc gRPC 将请求头/请求体转发给 gateway-plugin监听 50052→ 插件从请求中提取模型名在endpoints.yaml中查找可用后端 → 使用配置的路由算法选出最佳后端 → 通过target-pod响应头把目标地址返回给 Envoy → Envoy 使用ORIGINAL_DST类型集群将请求路由到该地址。这一机制在 deployment/local/configs/envoy.yaml 中有完整的静态配置印证。其中original_destination_cluster集群的配置如下- name: original_destination_cluster type: ORIGINAL_DST lb_policy: CLUSTER_PROVIDED original_dst_lb_config: use_http_header: true http_header_name: target-pod connect_timeout: 30s即 Envoy 通过读取target-pod请求头来决定上游地址而不是依赖 DNS 或 EDS 服务发现这正是裸进程模式下无需注册中心即可动态路由的关键。ext_proc 过滤器的处理模式也值得关注见 envoy.yamlprocessing_mode: request_header_mode: SEND request_body_mode: BUFFERED response_header_mode: SEND response_body_mode: STREAMED request_trailer_mode: SKIP response_trailer_mode: SKIP message_timeout: 600s failure_mode_allow: false请求体采用 BUFFERED缓冲后整体发送响应体采用 STREAMED流式转发适合 LLM 的流式输出场景failure_mode_allow: false表示插件处理失败时请求直接失败避免无谓地放行到错误后端。前置准备Go、gateway-plugin、Envoy、vLLM1. 安装 Go1.22Linuxwget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz sudo rm -rf /usr/local/go sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz echo export PATH$PATH:/usr/local/go/bin ~/.bashrc source ~/.bashrc go versionmacOSbrew install go2. 构建 gateway-plugin 二进制make build-gateway-plugins-nozmq该命令在 Makefile 中定义build-gateway-plugins-nozmq: manifests generate fmt vet ## Build gateway-plugins binary without ZMQ (for standalone mode).产物为bin/gateway-plugins——一个纯 Go 二进制不依赖 ZMQ/CGO。由于本地模式下没有 KV 事件同步等 ZMQ 相关需求这个构建目标是 standalone 模式的专用产物也避免了交叉编译 CGO 的麻烦。3. 安装 EnvoyLinuxx86_64ENVOY_VERSION1.37.1 wget -O envoy https://github.com/envoyproxy/envoy/releases/download/v${ENVOY_VERSION}/envoy-${ENVOY_VERSION}-linux-x86_64 chmod x envoy sudo mv envoy /usr/local/bin/ envoy --versionmacOSbrew install envoy4. 启动 vLLM 引擎# 示例在 8000 端口启动 vLLM vllm serve Qwen/Qwen3.5-4B --port 8000本地模式下 vLLM 可以与 Envoy 运行在同一台机器127.0.0.1:8000也可以运行在局域网内其他机器用可达的 IP 或主机名即可。5. 可选RedisRedis 在本地模式不是必需的。没有 Redis 时限流rate limiting功能会被禁用但路由功能正常工作。只有当你需要测试限流能力时才需要启动redis-server快速启动一键脚本与手动方式仓库提供了两个管理脚本但它们仅支持 Linux内部依赖setsid、ss、pgrep等 Linux 工具。macOS 用户需要手动启动两个进程。Linux 一键启动cd deployment/local # 编辑 endpoints 以匹配你的 vLLM 配置 vim configs/endpoints.yaml # 启动 ./run-local.sh # 测试 curl http://localhost:10080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen3.5-4B, messages: [{role: user, content: Hello}] } # 停止 ./stop-local.shmacOS 手动启动# macOS: start manually bin/gateway-plugins --standalone --endpoints-configdeployment/local/configs/endpoints.yaml envoy -c deployment/local/configs/envoy.yaml --use-dynamic-base-id --log-level warn macOS 手动停止手动启动时可用jobs/kill结束对应进程Linux 场景下直接运行./stop-local.sh即可脚本会读取deployment/local/.pids文件中的两个 PID 并逐一终止同时清理/dev/shm/envoy_shared_memory_*共享内存文件避免重启时因 Envoy base_id 冲突而启动失败。run-local.sh 做了什么阅读 run-local.sh 可以了解脚本的完整逻辑这对理解本地模式的进程管理非常有帮助依次检查 gateway-plugin 二进制、envoy命令、Envoy 配置与 endpoints 配置是否存在缺失时给出明确的修复提示通过setsid --fork启动 gateway-plugin--standalone --endpoints-config --grpc-bind-address:50052 --http-bind-address:8080日志重定向到logs/gateway-plugin.log轮询等待 gateway gRPC 端口 50052 就绪最多 30 秒失败则打印日志并退出再启动 Envoy-c configs/envoy.yaml --use-dynamic-base-id --log-level warn日志写入logs/envoy.log轮询等待 HTTP 端口 10080 就绪最多 10 秒最后把两个 PID 写入.pids文件并打印所有可用的端点地址与测试命令。配置详解Endpoints 配置configs/endpoints.yamldeployment/local/configs/endpoints.yaml 定义了网关可路由的 vLLM 后端地址支持三种形态。单后端最简形态models: - name: Qwen/Qwen3.5-4B engine: vllm # optional: vllm, sglang, trtllm endpoints: - 127.0.0.1:8000多后端网关在其间做负载路由models: - name: Qwen/Qwen2.5-1.5B-Instruct engine: vllm endpoints: - 192.168.1.10:8000 - 192.168.1.11:8000P/D 分离部署prefill/decode 角色分离models: - name: Qwen/Qwen2.5-72B engine: vllm rolesets: - name: default prefill: - 192.168.1.10:8000 decode: - 192.168.1.11:8000字段说明name模型名必须与请求体中的model字段完全一致否则路由无法命中engine可选字段取值vllm、sglang、trtllm用于标识后端引擎类型从源码看PD 分离场景下的引擎处理在 pkg/plugins/gateway/algorithms/pd/engine/ 目录分别实现了vllm、sglang、trtllm等处理器endpoints后端地址列表ip:port多地址时由路由算法选择rolesetsP/D 分离模式下的角色集合prefill与decode分别列出两类工作节点的地址。注意endpoints.yaml中的地址应使用本机可达的真实 IP 或主机名配置注释中明确说明 Use real IP addresses or hostnames reachable from this machine。Envoy 配置configs/envoy.yamldeployment/local/configs/envoy.yaml 是裸进程模式的完整 Envoy 静态配置几个关键点Admin 接口绑定127.0.0.1:9901可用于查看 stats 与 config dumpHTTP 监听器绑定0.0.0.0:10080针对 LLM 长请求设置了stream_idle_timeout: 300s与request_timeout: 600s避免推理耗时长导致连接被过早回收路由规则/v1/models→ 转发到gateway_http集群由 gateway-plugin 的 HTTP 服务兜底返回模型列表因为本地模式没有 metadata 服务/v1/→ 转发到original_destination_cluster核心推理路径timeout: 600s、idle_timeout: 300s/healthz→ 直接返回{status:ok}/metrics→ 转发到gateway_http其余路径 → 404 并提示使用/v1/chat/completions、/v1/messages或/v1/models。三个静态集群gateway_ext_proc指向127.0.0.1:50052HTTP/2用于 ext_proc gRPC、gateway_http指向127.0.0.1:8080用于 metrics 与模型列表、original_destination_clusterORIGINAL_DST类型读取target-pod头。关于/v1/models在本地模式下由插件直接应答这一点源码中有直接注释印证pkg/plugins/gateway/gateway.go 中 In local/standalone mode, Envoy routes /v1/models here since there is no metadata service同时 pkg/plugins/gateway/gateway.go 中 Skip validation in standalone mode (no gateway client) 说明 standalone 模式下插件跳过对 Kubernetes 网关客户端的依赖这正是它能脱离集群运行的原因。路由算法配置路由算法通过环境变量在启动前设置ROUTING_ALGORITHMround_robin ./run-local.shrun-local.sh 中给出了默认值ROUTING_ALGORITHM${ROUTING_ALGORITHM:-random}即不设置时默认使用random该变量会透传给 gateway-plugin 进程。更完整的变量说明可参考 pkg/plugins/gateway/ENV_VARS.md其中记录了ROUTING_ALGORITHM作为无 per-request 覆盖时的默认路由算法。原文档列出的可用算法包括random、round_robin、least_request、prefix_cache_aware等。需要说明的是从源码中的注册表看pkg/plugins/gateway/algorithms/ 目录下实际注册的算法名采用 kebab-case连字符命名包括但不限于算法名源码注册名实现文件说明randomrandom.go随机选择后端least-requestleast_request.go选择当前活跃请求最少的后端prefix-cacheprefix_cache.go优先选择命中前缀缓存的后端least-latencyleast_latency.go选择预估延迟最低的后端power-of-twopower_of_two.go两随机候选择优load-balanceload_balance.go基于待处理时间与 KV 缓存使用率的负载均衡throughputthroughput.go基于吞吐量的路由pdpd_disaggregation.goP/D 分离场景专用least-busy-time、least-gpu-cache、least-kv-cache、least-util、prefix-cache-preble等对应同名文件分别面向忙时、GPU/KV 缓存余量、利用率、带直方图的 Prefix Cache 等场景若你想组合多个算法并分配权重router.go 中的ParseMultiRouterConfig支持prefix-cache:2,least-latency:1,least-request这样的格式权重为 01000000 的整数缺省为 1权重 0 表示跳过。实际使用哪个命名风格建议以当前仓库源码注册名为准并在本地实测验证。端点一览启动成功后本地模式提供以下端点端点端口说明HTTP API10080推理请求入口如/v1/chat/completionsEnvoy Admin9901Envoy 管理接口stats、config dumpGateway Metrics8080gateway-plugin 的 Prometheus 指标Health Check10080/healthzEnvoy 健康检查另外模型列表接口为http://localhost:10080/v1/models指标地址为http://localhost:8080/metrics二者在 run-local.sh 启动成功后的输出中都会打印。日志本地模式下两个进程的日志分别落盘tail -f deployment/local/logs/gateway-plugin.log tail -f deployment/local/logs/envoy.loggateway-plugin.loggateway-plugin 的启动与运行日志插件崩溃、路由算法初始化失败等都会记录在这里envoy.logEnvoy 的运行日志--log-level warn级别端口冲突、配置错误等问题会体现在这里。排障指南报错/现象原因与排查no healthy upstreamvLLM 后端在endpoints.yaml中配置的地址不可达。确认引擎确实在运行、地址端口正确且本机可连通ext_proc gRPC errorgateway-plugin 未运行或已崩溃。检查logs/gateway-plugin.log确认插件状态Envoy wont start查看logs/envoy.log。最常见的原因是 10080 或 9901 端口被占用Routing not working检查请求中的model字段是否与endpoints.yaml中的name完全一致含大小写不一致时无法命中后端除以上原文档列出的常见问题外结合 stop-local.sh 的实现还可以补充一点重启前若残留/dev/shm/envoy_shared_memory_*可能导致 Envoy base_id 冲突而无法启动Linux 下请优先使用./stop-local.sh正常停止脚本会代为清理。小结本地模式以最小的依赖Go Envoy gateway-plugin 二进制复现了 AIBrix 网关的核心路径ext_proc 请求外发、模型名解析、路由算法选后端、target-pod头回传、ORIGINAL_DST集群转发。它适合路由算法的本地迭代与单机验证当需要 PodAutoscaler、ModelAdapter、KV Cache 等编排能力时则需要切换到完整的 Kubernetes 部署形态参考 config/default/kustomization.yaml 与 deployment/standalone/README.md。建议读者在动手前先通读 run-local.sh、envoy.yaml 与 endpoints.yaml 三份核心文件再结合本文逐步实践。【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考