AIBrix Runtime 实战指南多源模型下载与 aibrix-runtime 观测【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrixAIBrix Runtime 是 AIBrix 中负责在推理 Pod 内管理模型生命周期的核心组件它通过 initContainer 从 HuggingFace、AWS S3、火山引擎 TOS 等多源拉取模型权重由 aibrix-runtime 边车sidecar对外暴露健康检查与指标端口并配合 vLLM 主容器完成模型服务。本文以 development/tutorials/runtime/README.md 为骨架结合仓库中三个可直接运行的 YAML 清单与 python/aibrix/aibrix/runtime 源码实现完整讲解模型下载Model Download与指标合并Metrics Merge两大主题读完后你可以直接在自己的 Kubernetes 集群上部署多源模型推理服务并理解其底层下载与观测机制。一、AIBrix Runtime Demo 总体结构development/tutorials/runtime/目录下包含 1 个导读文档和 3 个完整的 Kubernetes 部署清单文件用途runtime-hf-download.yaml从 HuggingFace Hub 下载模型并启动 vLLM 服务runtime-s3-download.yaml从 AWS S3 下载模型并启动 vLLM 服务runtime-tos-download.yaml从火山引擎 TOS 下载模型并启动 vLLM 服务三个清单的骨架完全一致差异仅体现在 initContainer 的--model-uri参数与鉴权环境变量上。README 给出的三种部署方式均为一条命令kubectl apply -f runtime-hf-download.yaml # 或 kubectl apply -f runtime-s3-download.yaml # 或 kubectl apply -f runtime-tos-download.yaml每个清单都由两部分组成Deploymentapps/v1以model.aibrix.ai/name: deepseek-coder-7b-instruct为标签标识模型包含 vllm-openai 主容器、aibrix-runtime 边车容器和 model-init 下载 initContainerServicev1以model.aibrix.ai/name为 selector 将 8000 端口暴露为 ClusterIP并携带prometheus-discovery: true标签与prometheus.io/scrape: true、prometheus.io/port: 8080注解供 Prometheus 发现边车指标。注意三个清单中的模型均以 deepseek-coder-7b-instruct 为演示对象主容器镜像固定为vllm/vllm-openai:v0.5.5边车与下载镜像均为aibrix/runtime:latest实际使用时可替换为你的模型与镜像版本。二、模型下载三种数据源Model DownloadREADME 明确指出AIBrix runtime 支持从不同数据源下载模型。其核心实现位于 python/aibrix/aibrix/downloader 包入口函数download_model(model_uri, local_path, model_name, download_extra_config, enable_progress_bar)见 downloader/init.py会根据model_uri的 scheme 自动选择对应的 Downloader。2.1 从 HuggingFace 下载执行命令kubectl apply -f runtime-hf-download.yaml清单中model-initinitContainer 的核心参数为initContainers: - name: model-init image: aibrix/runtime:latest command: - python - -m - aibrix.downloader - --model-uri - deepseek-ai/deepseek-coder-6.7b-instruct - --local-dir - /models/ - --model-name - deepseek-coder-7b-instruct env: - name: DOWNLOADER_ALLOW_FILE_SUFFIX value: json, safetensors - name: HF_TOKEN value: input your hf token, if needed - name: HF_ENDPOINT value: input your hf endpoint, if needed - name: HF_REVISION value: input your mdoel revision, if needed volumeMounts: - mountPath: /models name: model-hostpath参数说明--model-uriHuggingFace 上的仓库 IDrepo_id如deepseek-ai/deepseek-coder-6.7b-instruct--local-dir模型落盘的基础目录默认/models/与主容器、边车通过共享卷model-hostpath挂载同一路径--model-name模型在本地目录下的子目录名即最终加载路径为/models/deepseek-coder-7b-instruct不设置时下载器会根据 URI 推断见 s3.py 中的infer_model_name逻辑各数据源一致DOWNLOADER_ALLOW_FILE_SUFFIX只下载指定后缀的文件示例限制为json, safetensors可显著减少无关文件的传输HF_TOKEN访问私有/受限模型时需要的 HuggingFace Token非必需按需填写HF_ENDPOINT自定义 HuggingFace 镜像端点如国内镜像站非必需HF_REVISION指定模型仓库的 revision分支/commit非必需。2.2 从 AWS S3 下载执行命令kubectl apply -f runtime-s3-download.yaml差异点仅在 initContainer- name: model-init image: aibrix/runtime:latest command: - python - -m - aibrix.downloader - --model-uri - s3://input your s3 bucket name/input your s3 bucket path - --local-dir - /models/ - --model-name - deepseek-coder-7b-instruct env: - name: DOWNLOADER_ALLOW_FILE_SUFFIX value: json, safetensors - name: AWS_ACCESS_KEY_ID value: input your s3 access key - name: AWS_SECRET_ACCESS_KEY value: input your s3 secret key - name: AWS_ENDPOINT_URL value: input your s3 endpoint - name: AWS_REGION value: input your s3 region参数说明--model-uri使用s3://bucket/path形式URI 会被解析为 bucket 与 bucket path见 s3.py 的_parse_bucket_info_from_uriAWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEYS3 访问密钥AWS_ENDPOINT_URL兼容 S3 协议的自建/第三方端点如 MinIO、R2 等非 AWS 官方 S3 时必填AWS_REGIONbucket 所在区域。源码细节S3 下载由S3BaseDownloader实现内部使用 boto3并通过TransferConfig支持多线程并发下载若未配置凭证会抛出明确的ModelNotFoundError并提示 IRSAIAM Role for Service Accounts的使用方式见 s3.py。2.3 从 TOS火山引擎对象存储下载执行命令kubectl apply -f runtime-tos-download.yaml差异点同样在 initContainer- name: model-init image: aibrix/runtime:latest command: - python - -m - aibrix.downloader - --model-uri - tos://input your tos bucket name/input your tos bucket path - --local-dir - /models/ - --model-name - deepseek-coder-7b-instruct env: - name: DOWNLOADER_ALLOW_FILE_SUFFIX value: json, safetensors - name: TOS_ACCESS_KEY value: input your tos access key - name: TOS_SECRET_KEY value: input your tos secret key - name: TOS_ENDPOINT value: input your tos endpoint - name: TOS_REGION value: input your tos region参数说明--model-uri使用tos://bucket/path形式TOS_ACCESS_KEY/TOS_SECRET_KEY火山引擎 TOS 的 AccessKey / SecretKeyTOS_ENDPOINTTOS 服务端点不配置时源码默认回退到tos-cn-beijing.volces.com见 runtime/downloaders.pyTOS_REGION区域默认回退到cn-beijing。从源码结构看AIBrix 的下载器还实现了 GCSgs://与 HTTP/HTTPS 数据源见 runtime/downloaders.py 与 L536-L634get_downloader会根据 URL scheme 在s3/gcs/tos/huggingface/http/https之间自动分发见 runtime/downloaders.py并统一采用先写.part临时文件、成功后os.replace原子改名的策略避免半截文件被 vLLM 误加载。2.4 下载层 CLI 与通用参数三个清单都通过python -m aibrix.downloader调用下载模块其 CLI 定义在 downloader/main.py除--model-uri、--local-dir、--model-name外还支持参数说明--enable-progress-bar从 TOS/S3 下载时展示进度条--download-extra-configJSON 字符串形式的额外配置如认证、并发参数其中--download-extra-config支持通过DOWNLOADER_*系列环境变量覆盖并发线程数等行为见 s3.py适合大模型权重在带宽充足时提高下载吞吐。三、aibrix-runtime 边车健康检查与探针无论从哪个数据源下载模型三个清单都部署了相同的aibrix-runtime边车容器- name: aibrix-runtime image: aibrix/runtime:latest command: - aibrix_runtime - --port - 8080 env: - name: INFERENCE_ENGINE value: vllm - name: INFERENCE_ENGINE_ENDPOINT value: http://localhost:8000 ports: - containerPort: 8080 volumeMounts: - mountPath: /models name: model-hostpath livenessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 3 periodSeconds: 2 readinessProbe: httpGet: path: /ready port: 8080 initialDelaySeconds: 5 periodSeconds: 10核心点aibrix_runtime --port 8080启动 FastAPI 服务启动参数定义见 app.py默认端口 8080INFERENCE_ENGINEvllmINFERENCE_ENGINE_ENDPOINThttp://localhost:8000告诉边车它所伴生的推理引擎类型与地址边车与 vLLM 主容器共享/models卷因此可以感知模型文件状态边车提供/healthz存活与/ready就绪两个探针端点与 vLLM 自身的/health8000 端口探针相互独立。3.1 从 vLLM 到 aibrix-runtimePod 内部署形态以 runtime-hf-download.yaml 为例Pod 内容器的协作关系为model-initinitContainer先于主容器运行用aibrix.downloader将模型从数据源拉取到共享的model-hostpath卷的/models目录vllm-openai主容器以--model /models/deepseek-coder-7b-instruct --served-model-name deepseek-coder-7b-instruct启动从本地共享卷加载权重监听 8000 端口同时开启--distributed-executor-backend ray与--trust-remote-codeaibrix-runtime边车以INFERENCE_ENGINE_ENDPOINThttp://localhost:8000指向主容器监听 8080 端口承载指标与健康检查。其余部署细节resources.limits/requests声明nvidia.com/gpu: 1请求 1 张 GPUdshm卷以emptyDir.medium: Memory、sizeLimit: 10Gi挂载到/dev/shm为 vLLM 的共享内存提供空间vLLM 主容器配置了initialDelaySeconds: 90的存活/就绪探针/health容忍大模型冷启动时间边车探针则短得多存活 3s 延迟/2s 周期就绪 5s 延迟/10s 周期用于快速反映边车自身状态Service 以model.aibrix.ai/name: deepseek-coder-7b-instruct作为 selector将 8000 端口以 ClusterIP 暴露供网关或客户端访问。四、指标合并Metrics Merge与观测README 的第二部分是Metrics Merge。结合仓库源码可以还原这一机制的完整实现aibrix-runtime 边车既是引擎生命周期管理器也是每个 Pod 上的指标聚合与透传点。4.1 边车的指标采集职责从 runtime/model_runtime_metrics.py 的模块注释可以看出边车通过 Prometheus Collector 暴露每 Pod 密度级指标挂在边车自身的/metrics端点上即 Service 注解prometheus.io/port: 8080所指向的抓取端口。其collect()是只读快照操作不会改变 agent 状态。主要指标包括指标名含义aibrix:modelclaim_models_resident本 Pod 上常驻引擎进程存活的模型数量aibrix:modelclaim_kv_used_bytes/aibrix:modelclaim_kv_total_bytes模型对应 kvcached 共享内存段的已用/总 KV 字节标签modelaibrix:modelclaim_hbm_peak_bytes该引擎在任一可见 GPU 上的最大显存占用标签modelaibrix:modelclaim_engine_state引擎处于 active/sleeping/restarting/failed 各状态的数量标签phase底层实现KV 字节来自对/dev/shm/ipc_name共享内存段头部的MemInfoStruct3 个 little-endian int64total/used/prealloc的读取见 model_runtime.py显存占用通过 NVML 读取可见 GPU 的内存快照并沿进程树vLLM 的 GPU 分配通常发生在 worker 子进程累加归属见 model_runtime.py。NVML 不可用时安全降级为空观测不影响控制面决策。4.2 引擎请求活跃度观测边车还会在本地仅 localhost抓取 vLLM 的/metrics解析vllm:num_requests_running、vllm:num_requests_waiting、vllm:request_success_total等指标兼容冒号与下划线两种命名风格并且只统计model_name标签与当前实例匹配的样本从而在多引擎共享 Prometheus 多进程目录时避免串扰见 model_runtime.py。抓取失败时返回未观测状态调用方不得据此推断引擎空闲。4.3 边车的控制面 API进阶阅读除观测外aibrix-runtime 边车还暴露了模型生命周期控制 API由 runtime/model_runtime_api.py 定义POST /v1/runtime/models/activate激活一个模型下载权重、以独立 kvcached 引擎进程拉起 vLLM/SGLangPOST /v1/runtime/models/deactivate停掉引擎进程以及 list / KV limit / sleep / wake 等扩展端点。这些端点由 ModelClaim 控制器通过 HTTP 驱动见 model_runtime.py 的模块说明。引擎启动器EngineLauncher是插件化的真实环境用SubprocessEngineLaunchervLLM 侧附加--enable-sleep-mode并设置VLLM_SERVER_DEV_MODE1以启用/sleep、/wake_up端点无 GPU 的测试环境则用MockEngineLauncher见 model_runtime.py 与 L775-L796保证 agent 在纯 CPU 环境也可完整测试。五、部署与验证建议5.1 部署前置条件一个可用的 Kubernetes 集群建议已安装 GPU 设备插件如 nvidia-device-plugin节点可见 GPU集群可拉取vllm/vllm-openai:v0.5.5与aibrix/runtime:latest镜像离线环境请先同步镜像若使用 S3/TOS确保model-init容器能访问对应对象存储的端点与凭据若模型在 HuggingFace 上为私有请提前填写HF_TOKEN。5.2 部署后的验证链路# 1. 应用清单 kubectl apply -f development/tutorials/runtime/runtime-hf-download.yaml # 2. 观察 Pod 状态initContainer 先完成下载主容器随后加载 kubectl get pods -l model.aibrix.ai/namedeepseek-coder-7b-instruct -w # 3. 查看下载与引擎日志 kubectl logs pod-name -c model-init kubectl logs pod-name -c vllm-openai # 4. 验证边车健康与就绪 kubectl port-forward svc/deepseek-coder-7b-instruct 8000:8000 curl http://localhost:8000/health # vLLM 健康检查 curl http://localhost:8000/v1/models # OpenAI 兼容模型列表 # 5. 验证边车指标端点需先转发 8080 端口 kubectl port-forward pod-name 8080:8080 curl http://localhost:8080/ready # 边车就绪 curl http://localhost:8080/healthz # 边车存活 curl http://localhost:8080/metrics # 边车合并后的 Prometheus 指标验证通过后即可通过 Servicedeepseek-coder-7b-instructClusterIP:8000以 OpenAI 兼容协议发起推理请求prometheus-discovery: true标签与prometheus.io/scrape: true注解让集群内的 Prometheus 能自动发现并抓取边车的指标配合 observability/grafana 下的 vLLM 引擎 Dashboard 即可完成端到端可观测。六、小结围绕development/tutorials/runtime/目录本文完成了三件事一是用一条kubectl apply命令分别演示了 HuggingFace、AWS S3、火山 TOS 三种模型下载源及其全部参数二是剖析了 Deployment Service 的完整部署形态initContainer 下载 → vLLM 主容器加载 → aibrix-runtime 边车观测三是从 python/aibrix/aibrix/runtime 源码层面还原了Metrics Merge的底层机制——边车通过/metrics聚合 KV 用量、HBM 占用、引擎状态与请求活跃度并通过/healthz、/ready支撑 Pod 探针。这套多源下载 边车观测的组合是 AIBrix 将推理服务接入统一网关、自动扩缩容与 kvcache 调度体系的基础设施底座。【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考