Cortex Realtime API 部署实战：从 FastAPI 服务到云端自动扩缩容（端到端指南）

后端云原生模型推理服务MLOps人工智能【免费下载链接】cortexProduction infrastructure for machine learning at scale项目地址https://gitcode.com/gh_mirrors/co/cortex点击查看免费下载导读本文以 Cortex 官方示例docs/workloads/realtime/example.md为主线完整走通「编写 FastAPI 服务 → 构建 Docker 镜像 → 推送到 Amazon ECR → 编写cortex.yaml→ 部署 Realtime API → 调用验证」的完整链路同时结合仓库内自动扩缩容实现、配置手册与测试示例深入讲解 Realtime API 的 proxy 架构、target_in_flight扩缩容公式、就绪探针、scale-to-zero、滚动更新与排障方法。读完本文你将具备在 Cortex 集群上独立交付一个可自动扩缩容的实时推理 API 的全部技能。一、Realtime API 是什么适合什么场景Realtime API 是 Cortex 面向同步请求场景提供的负载类型客户端发来请求后API同步地返回响应并根据**在途请求数in-flight requests**自动扩缩容。根据 realtime.md 的说明它非常适合运行无状态容器并把机器学习模型封装成可横向扩展的微服务。其核心特性包括同步响应请求-响应模式天然适配在线推理基于请求量自动扩缩容无人工干预地随流量增减副本避免冷启动默认保持最小副本随时可以承接流量支持 scale-to-zero实验特性流量归零时缩到 0 个副本借助 activator 接收请求滚动更新更新镜像/配置时平滑替换旧副本故障自愈自动从容器崩溃、Spot 实例被回收等故障中恢复A/B 测试与金丝雀发布通过 TrafficSplitter 将流量按权重分发到多个 Realtime API。从实现角度看Realtime API 由 Kubernetes Deployment 自动注入的 proxy sidecar 组成proxy 负责接收请求、排队、转发并上报指标autoscaler 基于这些指标做扩缩容决策详见下文自动扩缩容原理。二、架构速览proxy sidecar 在途请求指标在深入示例前先理解运行时结构依据 realtime.md 与源码部署 Realtime API 时Cortex 会初始化一个 worker pod 池并给每个 pod 注入一个 proxy sidecar 容器proxy 负责接收来自负载均衡器的请求、在必要时排队、在 pod 就绪后转发到你的业务容器自动扩缩容基于聚合后的在途请求数cortex_in_flight_requests指标该指标由 proxy sidecar 上报。在源码中可以看到这条数据链路pkg/proxy/request_stats.go 定义了RequestStats与PrometheusStatsReporterproxy 周期性统计在途请求并写入名为cortex_in_flight_requests的 Prometheus Gaugepkg/autoscaler/realtime_scaler.go 中的GetInFlightRequests通过 PromQL 查询在途请求数并除以副本数得到每副本平均在途请求sum(sum_over_time(cortex_in_flight_requests{api_nameapiName}[60s])) / max(count_over_time(cortex_in_flight_requests{api_nameapiName, container!activator}[60s]))而Scale方法负责把决策结果写回 Deployment 的spec.replicas当缩到 0 时会通过routeToActivator把流量切到 activator重新扩起来时再通过routeToService切回 API详见 realtime_scaler.go。三、端到端示例从零部署一个 hello-world Realtime API下面完整复现官方示例example.md每一步都给出可直接复制的代码与命令。仓库中对应的完整测试样例位于 test/apis/realtime/hello-world可作为对照参考。3.1 定义 API一个 FastAPI 应用创建main.py定义接受 POST 请求的 FastAPI 应用# main.py from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Data(BaseModel): msg: str app.post(/) def handle_post(data: Data): return dataFastAPI 会自动把 JSON 请求体解析为Data模型并把msg字段原样返回使用 Pydantic 做请求校验缺少msg字段的请求会返回 422更贴近仓库真实测试样例的版本见 test/apis/realtime/hello-world/app/main.py它还额外暴露了一个/healthz就绪探针端点后面会讲到。3.2 创建 DockerfileFROM python:3.8-slim RUN pip install --no-cache-dir fastapi uvicorn COPY main.py / CMD uvicorn --host 0.0.0.0 --port 8080 main:app关键点容器内 Web 服务器必须监听pod.port配置的端口默认 8080Cortex 会把pod.port的值通过环境变量CORTEX_PORT注入容器。仓库样例 test/apis/realtime/hello-world/cpu.Dockerfile 展示了更规范的做法ENV CORTEX_PORT8080并在 CMD 中引用--port $CORTEX_PORT这样端口配置只需在cortex.yaml中改一处。3.3 本地构建并运行容器先在本机构建镜像确保服务本身没问题docker build . -t hello-world在本地运行容器并映射端口docker run -p 8080:8080 hello-world3.4 本地发请求验证curl -X POST -H Content-Type: application/json -d {msg: hello world} localhost:8080预期返回{msg:hello world}说明业务逻辑与监听端口都正确。3.5 推送到 Amazon ECRRealtime API 的镜像需要被集群内的节点拉取因此需要推送到 ECR前提你的集群节点具备对应的 ECR 拉取权限。第一步登录 ECR示例为us-east-1区域aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com第二步创建仓库aws ecr create-repository --repository-name hello-world第三步打标签docker tag hello-world AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/hello-world第四步推送docker push AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/hello-world如果镜像不可访问副本会处于ErrImagePull状态见下文副本状态表此时应检查镜像是否存在、以及集群节点的 AWS 凭据是否有权限。3.6 编写 cortex.yaml 部署配置在项目根目录创建cortex.yaml声明一个 Realtime API# cortex.yaml - name: hello-world kind: RealtimeAPI pod: containers: - name: api image: AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/hello-world这是最小可用配置name指定 API 名称同时默认作为访问端点kind必须是RealtimeAPIpod.containers至少提供一个容器。仓库中的完整测试样例 test/apis/realtime/hello-world/cortex_cpu.yaml 在此基础上增加了port、max_concurrency、就绪探针与计算资源声明建议直接参考。3.7 部署到集群在包含cortex.yaml的目录下执行cortex deploycortex deploy支持[CONFIG_FILE]参数、-y跳过交互提示、-o json|pretty指定输出格式参见 docs/clients/cli.md 中 deploy 命令说明。部署后可以用cortex get查看所有 API 的状态。3.8 等待 API 就绪cortex get --watch--watch会每 2 秒刷新一次直到 API 状态变为live、up-to-date与requested副本数一致。就绪的定义是所有容器的就绪探针readiness probe通过、pod 处于可接收流量状态。3.9 获取 API 端点cortex get hello-world该命令会显示 API 的负载均衡器 URL形如http://***.amazonaws.com/hello-world同时给出近两周的平均请求耗时与响应码计数详见 metrics.md 的示例输出env api status up-to-date requested last update avg request 2XX cortex iris-classifier live 1 1 17m 24ms 12233.10 向云端 API 发请求curl -X POST -H Content-Type: application/json -d {msg: hello world} http://***.amazonaws.com/hello-world注意端点 URL 以/hello-world结尾——Cortex 会把load_balancer_url/hello-world路由到你容器的根路径/详见下文请求路由与子路径。四、cortex.yaml 配置详解从最小示例到生产级官方配置手册 configuration.md 给出了完整字段以下按功能域展开默认值均以当前仓库文档为准。4.1 pod 配置端口、并发与排队pod: port: 8080 # 请求发送到容器的端口默认 8080导出为 $CORTEX_PORT 环境变量 max_concurrency: 1 # 同时进入容器处理的最大请求数默认 1 max_queue_length: 100 # 每副本允许排队的最大请求数超过 max_concurrency超出后返回 503默认 100 containers: # 至少一个容器 - name: api image: imageport业务容器中 HTTP 服务器监听的端口Cortex 通过环境变量CORTEX_PORT注入max_concurrency如果 Web 服务器能并发处理多个请求调高它可以提升单副本吞吐、降低所需副本总数依据 autoscaling.mdmax_queue_lengthproxy 为每个副本保留的队列长度超出max_concurrency的部分。对长耗时 API调小该值并让客户端在收到 503 时重试可以防止请求长时间堆积在某个副本队列中改善副本间的公平性。4.2 容器定义command / args / env / compute / probescontainers: - name: api image: image command: [uvicorn] # 入口命令不使用 shell可用 $(CORTEX_PORT) 引用环境变量 args: [--host, 0.0.0.0, --port, 8080, main:app] env: # 注入的环境变量字典可选 MODEL_PATH: /models/resnet50 compute: # 计算资源请求 cpu: 200m # CPU 请求1 1 vCPU支持小数与 m 后缀默认 200m gpu: 0 # GPU 请求默认 0 inf: 0 # AWS Inferentia 芯片请求默认 0 mem: 128Mi # 内存请求支持 K/M/G/T 与 Ki/Mi/Gi/Ti默认 Null shm: 64Mi # /dev/shm 共享内存大小用于多进程共享数据默认 Null readiness_probe: # 就绪探针全部通过后才向 pod 转发流量 http_get: port: 8080 path: /healthz # tcp_socket: {port: 8080} # 或 TCP 探针 # exec: {command: [/bin/check]} # 或 exec 探针 initial_delay_seconds: 0 # 容器启动后延迟开始探测的秒数默认 0 timeout_seconds: 1 # 探测超时秒数默认 1 period_seconds: 10 # 探测周期秒数默认 10 success_threshold: 1 # 连续成功多少次视为通过默认 1 failure_threshold: 3 # 连续失败多少次视为失败默认 3 liveness_probe: # 存活探针失败则重启容器字段同上 http_get: port: 8080 path: /healthz pre_stop: # 终止前钩子可选支持 http_get 与 exec http_get: port: 8080 path: /shutdown说明command/args默认分别沿用镜像的ENTRYPOINT/CMD都支持$(CORTEX_PORT)这类环境变量引用compute.cpu默认 200m即 0.2 vCPU就绪探针的三种类型http_get/tcp_socket/exec三选一就绪探针的意义在请求处理细节一节展开。4.3 autoscaling 配置autoscaling: min_replicas: 1 # 最小副本数默认 1支持 0即 scale-to-zero实验特性 max_replicas: 100 # 最大副本数默认 100 init_replicas: 1 # 初始副本数默认等于 min_replicas target_in_flight: 1 # 每副本目标在途请求数默认等于 max_concurrency window: 60s # 在途请求的平均窗口默认 60s必须为 10s 的倍数 downscale_stabilization_period: 5m # 该时段内取最高建议防止频繁缩容默认 5m upscale_stabilization_period: 1m # 该时段内取最低建议防止频繁扩容默认 1m max_downscale_factor: 0.75 # 单次缩容最大倍数默认 0.75 max_upscale_factor: 1.5 # 单次扩容最大倍数默认 1.5 downscale_tolerance: 0.05 # 建议低于当前副本数且在该因子内时不触发缩容默认 0.05 upscale_tolerance: 0.05 # 建议高于当前副本数且在该因子内时不触发扩容默认 0.054.4 更新策略与网络配置update_strategy: max_surge: 25% # 更新期间最多超过期望副本数的量可为绝对数5或百分比10%默认 25%设为 0 禁用滚动更新 max_unavailable: 25% # 更新期间最多不可用副本数默认 25% networking: endpoint: hello-world # API 访问端点默认等于 API 名称 node_groups: [] # 限定可调度的节点组默认所有节点组update_strategy与 Kubernetes Deployment 的滚动更新语义一致用于保证更新镜像/配置时服务不中断networking.endpoint决定 API 对外暴露的 URL 路径默认是 API 名称node_groups可用于把 API 约束到特定硬件如 GPU 节点组。五、自动扩缩容原理与调优Cortex 对每个 API 独立做扩缩容决策依据是target_in_flight每副本目标在途请求数。依据 autoscaling.md核心公式为desired replicas sum(in-flight requests across all replicas) / target_in_flight其中在途请求 已发送给副本但尚未收到响应的请求因此既包括正在处理的请求也包括在队列中等待的请求。默认target_in_flight max_concurrency时集群会维持副本数使请求平均无需排队即可被处理。5.1 平滑扩缩稳定窗口、速率因子与容差window默认 60s在途请求按该窗口求平均后再决策。指标每 10 秒计算一次因此window必须是 10 秒的倍数downscale_stabilization_period默认 5m取该时段内最高的建议副本数作为下限抑制流量骤降时的抖动upscale_stabilization_period默认 1m取该时段内最低的建议副本数作为上限抑制流量突增时的过冲max_downscale_factor默认 0.75单次缩容最多缩减到当前值的该比例如 10 个副本单次至少保留 7.5→7/8 个max_upscale_factor默认 1.5同理限制单次扩容上界downscale_tolerance/upscale_tolerance默认 0.05建议值落在当前副本数的该容差范围内就不触发缩放避免频繁抖动例如 20 个副本时建议 18、19 都不会触发缩容。5.2 scale-to-zero请求如何被激活将min_replicas设为 0 即可启用 scale-to-zero实验特性。仓库测试样例 test/apis/realtime/hello-world/cortex_scale_to_zero.yaml 就是典型配置autoscaling: min_replicas: 0 max_replicas: 1 downscale_stabilization_period: 30s从 realtime_scaler.go 的实现可以看出其工作机制当建议副本数为 0 时autoscaler 先调用routeToActivator把 Istio VirtualService 的流量权重从 API100/0切到 activator0/100再把spec.replicas置 0当有请求到达时activator 会持有请求并触发扩容autoscaler 在waitForReadyReplicas确认存在就绪副本后调用routeToService把流量切回 API。这就是请求不丢、冷启动可接受的 scale-to-zero 实现路径。5.3 超配overprovisioning以应对流量尖峰默认target_in_flight max_concurrency在多数场景表现良好但如果你的应用对突发流量敏感、或者新副本创建耗时较长可以通过降低target_in_flight来保留富余容量例如每个副本能高效处理 2 个并发请求通常设target_in_flight: 2。平均 8 个并发请求时autoscaler 维持 4 个副本8/24。若想超配 25%设target_in_flight: 1.6则维持 5 个副本8/1.65多出的副本即为应对突发流量的缓冲。target_in_flight越小API 的闲置容量越大抗突发能力越强代价是常驻成本更高。5.4 扩缩容响应时间预期依据 autoscaling.md在默认参数window60s、upscale_stabilization_period1m下从流量上升到触发扩容最多可能需要 2 分钟新副本被请求后如果还需要 AWS 新建实例则要再加上实例供给、拉取镜像与容器初始化时间数分钟不等。若希望 autoscaler 尽可能快地响应可把upscale_stabilization_period设为0s、window设为最小10s。六、请求处理细节子路径、就绪检查、多容器与链式调用6.1 请求路由与子路径依据 containers.mdAPI 名为hello-world时load_balancer_url/hello-world会被路由到 Web 服务器的根路径/而load_balancer_url/hello-world/subpath会被路由到服务器的/subpath——也就是说API 的 endpoint 在负载均衡层被剥离你无需在业务代码里处理 API 名前缀。6.2 就绪检查readiness checks默认情况下容器一旦绑定端口就开始接收流量但有些 Web 服务器如tiangolo/uvicorn-gunicorn-fastapi会在 worker 真正就绪前就监听端口此时流量可能被丢弃。解决办法是在服务中暴露一个返回 200 的路径如/healthz并配置就绪探针readiness_probe: http_get: port: 8080 path: /healthz只有 pod 内所有容器的就绪探针通过后proxy 才会向该 pod 转发流量。仓库测试样例 cortex_cpu.yaml 即采用此模式。6.3 多容器与共享目录一个 pod 可以包含多个容器但只有一个容器在目标端口上监听请求可以是其中任意一个。Cortex 会把/mnt目录挂载到每个容器并共享适合边车sidecar模式例如主服务 模型加载器共用/mnt中的模型文件。6.4 资源请求与 proxy 开销每个容器各自声明 CPU/内存/GPU/Inferentia 资源此外 Cortex自动注入的 proxy sidecar 会额外请求 100m CPU 与 100Mi 内存规划节点容量时需把这部分算进去。6.5 在容器内使用 Cortex CLI / Python client所有 API 容器内都会预置客户端配置文件/cortex/client/cli.yaml连接指向本集群环境变量CORTEX_CLI_CONFIG_DIR默认指向/cortex/client因此容器内可以直接用 CLI 或 Python clientcortex.client()访问集群中的其他 API无需额外配置。注意 CLI/client 版本应与集群版本见环境变量CORTEX_VERSION一致。6.6 API 链式调用Chaining APIs集群内的任意 Cortex API 都可以通过集群内部地址调用 Realtime APIimport requests response requests.post( http://ingressgateway-apis.istio-system.svc.cluster.local/hello-world, json{text: hello world}, )注意如果是 Realtime/Async API 发起这种链式调用其target_in_flight配置需要考虑到请求在第二个 API 执行期间在第一个 API 中也会被计为在途请求。七、副本状态、可观测性与排障7.1 副本状态表执行cortex describe api-name可以查看每个副本的状态。依据 statuses.md状态含义Ready副本运行中且已通过就绪检查ReadyOutOfDate副本运行中且通过就绪检查但属于旧版本NotReady副本运行中但未通过就绪检查请确认服务监听了 API 配置的端口Pending副本等待被调度到节点上Creating副本正在创建容器ErrImagePull镜像在运行时不可访问检查镜像是否存在、集群节点 AWS 凭据是否有权限Failed副本启动失败运行cortex logs name查看日志Killed副本有容器被杀死KilledOOM副本因内存超限被终止尝试给 API 分配更多内存后重新部署Stalled副本处于 Pending 超过 15 分钟参见 troubleshootingTerminating副本正在被终止Unknown未知状态7.2 可观测性cortex get/cortex get api展示近两周的平均请求耗时与响应码计数metrics.md每个 API 还有对应的 Grafana 面板包含 Request Rate、In Flight Request每 10 秒记录一次、Active Replicas、2XX/4XX/5XX 响应速率、p99/p90/p50 与平均延迟等面板日志与告警配置参见 clusters/observability/logging.md 与 clusters/observability/metrics.md。7.3 常见问题503 与 stuck updating依据 troubleshooting.md503 no healthy upstream当前没有任何存活副本。可能原因API 尚未就绪用cortex get api查看就绪副本数、用cortex logs api查日志或 API 在初始化/处理请求时报错用cortex describe api查看失败副本数。若前面加了 API Gateway超过其 29 秒超时也会返回 503此时应缩短请求耗时、换用更快硬件如 GPU或去掉 API Gateway直接使用 API 端点没有超时限制。API 卡在 updating副本长时间处于pending/stalled时依次排查cortex logs api获取 CloudWatch 日志 URL 检查基础设施与容器日志检查集群max_instances如果某节点组已达上限新实例无法创建API 就无法部署/扩容/更新。用cortex cluster info --config cluster.yaml查看当前上限按 update.md 的指引调高在 AWS 控制台查看 Auto Scaling Group 的 Activity/Activity History确认实例供给失败的具体原因。八、A/B 测试与金丝雀发布当需要对比两个模型版本或做灰度发布时可以用 TrafficSplitter 把多个 Realtime API 暴露为单一端点按权重分流非 shadow 权重之和必须为 100支持shadow影子流量仅复制流量做 fire-and-forget 验证每个 splitter 最多一个 shadow- name: sentiment-analyzer kind: TrafficSplitter apis: - name: sentiment-analyzer-a weight: 50 - name: sentiment-analyzer-b weight: 50之后只需重新 deploy 修改权重即可逐步放量实现金丝雀或多臂老虎机实验。九、小结从示例到生产的关键 checklist回到本文主线的 hello-world 示例一个生产可用的 Realtime API 至少应做到容器正确监听CORTEX_PORT默认 8080并用环境变量注入端口避免硬编码配置 HTTP 就绪探针如/healthz避免流量打到未就绪的 worker为容器声明合理的compute资源并记住 proxy sidecar 额外占用 100m CPU 100Mi 内存按延迟/吞吐画像设置max_concurrency、max_queue_length与target_in_flight必要时用超配应对突发按需开启 scale-to-zeromin_replicas: 0并用downscale_stabilization_period抑制抖动用update_strategy控制滚动更新节奏多版本对比交给 TrafficSplitter监控副本状态cortex get看整体、cortex describe看副本、cortex logs看日志。沿着 example.md 的步骤配合 configuration.md 的字段手册与 autoscaling.md 的原理说明你就能把任意 FastAPI/TorchServe 之类的无状态推理服务稳定地跑在 Cortex 的自动扩缩容体系之上。赞分享后端云原生模型推理服务MLOps人工智能【免费下载链接】cortexProduction infrastructure for machine learning at scale项目地址https://gitcode.com/gh_mirrors/co/cortex点击查看免费下载相关推荐Qwen3部署实战从本地推理到云端服务Qwen3部署实战从本地推理到云端服务 本文全面介绍了Qwen3大语言模型的多种部署方案涵盖了从本地CPU推理优化到云端高性能服务的完整技术栈。详细讲解了T人工智能大模型Qwen模型评测示例工程本地部署教程BentoML 统一推理平台从模型服务 API 到云端自动扩缩容的完整上手指南BentoML 统一推理平台从模型服务 API 到云端自动扩缩容的完整上手指南 本文以 BentoML 官方文档入口 docs/source/index.r模型推理服务人工智能后端大模型MLOpsLLMOpsFlowsint API 服务端实战从 uv 安装到 uvicorn 启动与容器化部署Flowsint API 服务端实战从 uv 安装到 uvicorn 启动与容器化部署 Flowsint 是一个面向网络安全分析人员与调查人员的可视化图调查平后端前端网络安全AI 应用图计算上一篇Chocolatey 容器化部署终极指南Windows 和 Linux Docker 快速配置下一篇彻底解决GitHub API调用难题go-github速率限制与错误处理实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考