企业官网建设流程全解析

• 后端
• 云原生
• 模型推理服务
• MLOps
• 人工智能

导读

本文聚焦 Cortex 项目中 Task API 的容器行为与容器内开发实践，系统讲解如何从容器内部读取 Job 完整规范（/cortex/spec/job.json）、利用多容器共享的/mnt目录构建 Sidecar 式工作流、在容器内直接使用 Cortex CLI / Python 客户端访问集群 API，以及如何通过 Istio Ingress Gateway 从任意 API 向 Task API 提交作业（Chaining APIs）。读完本文，你将能够在 Task API 的容器代码中熟练完成"读取作业参数、跨容器协作、调用集群 API、链式提交任务"这四类高频场景。

Task API 与容器模型概览

在深入容器细节之前，先明确 Task API 的运行时模型（参见 Task API 总览）：当你部署一个 Task API 后，Cortex 会创建一个接收作业提交的 HTTP 端点；提交作业后，Cortex 返回一个job_id，并异步初始化一个 worker Pod（基于 API 的 pod 配置），Pod 运行完成后任务被标记为 completed，Pod 随即终止。Task API 支持按需运行、无任务时缩容到 0、以及自动从故障与 Spot 实例终止中恢复。

因此，容器配置（pod.containers）直接决定了 worker Pod 中实际运行的程序。理解容器内可用的约定路径、环境变量与网络访问方式，是编写正确 Task 应用的前提。

读取完整 Job 规范：/cortex/spec/job.json

规范文件的产生与结构

当 Task 作业被提交后，Cortex 会将**整个 Job 规范（job specification）**写入 API 容器的文件系统，路径固定为/cortex/spec/job.json。也就是说，只要你在容器代码中读取该文件，就能获得本次提交的完整参数，包括config字段中的任意自定义输入。

从源码看，Task 作业提交的载荷结构由TaskJobSubmission定义（pkg/operator/schema/job_submission.go），它内嵌了RuntimeTaskJobConfig（pkg/types/spec/job.go）：

type RuntimeTaskJobConfig struct { Workers int `json:"workers" yaml:"workers"` Config map[string]interface{} `json:"config" yaml:"config"` Timeout *int `json:"timeout" yaml:"timeout"` }

用户通过 HTTP 提交的载荷形如（参见 TaskAPI jobs）：

{ "timeout": 3600, "config": {"my_key": "my_value"} }

Cortex 在SubmitTaskJob处理器中（pkg/operator/endpoints/submit_task.go）将Workers固定为 1，随后把用户提交的timeout与config合并进作业规范，并以 JSON 形式写入 S3；worker Pod 启动时该规范被下载并挂载到/cortex/spec/job.json。作业规范的 S3 存储路径格式可在 pkg/types/spec/job.go 中看到：

/<cluster UID>/jobs/<job_api_kind>/<cortex version>/<api_name>/<job_id>/spec.json

在容器中读取配置的推荐方式

在你的应用入口处读取并解析/cortex/spec/job.json即可获得本次作业的config。例如：

import json with open("/cortex/spec/job.json") as f: job_spec = json.load(f) config = job_spec.get("config", {}) my_value = config.get("my_key")

这意味着任务参数无需硬编码进镜像或命令行——每次提交作业时通过config传入即可，容器代码保持不变。这一机制让同一个 Task API 可以服务于大量参数不同的作业。

多容器协作：共享的 /mnt 目录

多容器布局

Task 的 worker Pod 可以包含多个容器（pod.containers中至少提供一个容器，参见 配置文档）。典型用法是一个容器承载主业务逻辑，另一个容器作为辅助进程（例如日志转发、指标采集的 Sidecar）。

/mnt 共享语义

所有容器都会挂载同一个/mnt目录，并且该目录在所有容器之间共享。因此，多容器之间可以通过/mnt下的文件进行数据交换：主容器将中间结果或待处理文件写入/mnt，辅助容器读取并消费。这是 Task（以及 Realtime、Batch、Async）容器协作的标准约定，无需额外配置即可使用。

值得注意的补充点是：compute.shm配置项可以单独设置共享内存（如64Mi或1Gi），用于同一容器内多进程之间的数据共享（挂载到/dev/shm），这与/mnt的跨容器共享是两套不同的机制（参见 配置文档 中shm字段说明）。

容器内可观测性

Task API 容器遵循与集群其他工作负载一致的日志、指标与告警约定，可直接沿用集群层面的观测能力：

• 日志：查看 集群日志观测指南；
• 指标：查看 集群指标观测指南；
• 告警：查看 集群告警指南。

作业级别的状态信息（status、created_time、start_time、end_time等）可通过cortex get <task_api_name> <job_id>或对 Task API 端点发起GET <endpoint>?jobID=<jobID>获取，响应结构见 TaskAPI jobs。

在容器内使用 Cortex CLI / Python 客户端

免配置的连接机制

每个容器都会自动携带一份已配置好的 CLI 配置文件，路径为/cortex/client/cli.yaml，它被预配置为连接到当前集群。同时，Cortex 会默认设置环境变量：

CORTEX_CLI_CONFIG_DIR=/cortex/client

从源码看，这个环境变量由 pkg/workloads/k8s.go 统一注入到每个容器：

containerEnvVars = append(containerEnvVars, kcore.EnvVar{ Name: "CORTEX_CLI_CONFIG_DIR", Value: _clientConfigDir, })

因此，容器内使用 CLI 或 Python 客户端无需任何额外配置。Python 客户端可以直接实例化（该客户端库位于 python/client/cortex）：

import cortex cx = cortex.client() # 之后即可用 cx 访问集群 API，例如获取 API 列表、提交任务等

CLI 同样开箱即用：

cortex get cortex get <api_name>

版本匹配约束

容器内使用的 Cortex CLI / 客户端版本必须与集群版本一致。集群版本可以通过环境变量CORTEX_VERSION读取：

echo $CORTEX_VERSION

在 Dockerfile 中安装客户端时，建议根据CORTEX_VERSION锁定对应版本（集群安装与版本管理可参考 安装指南 与 CLI 文档），避免因版本不匹配导致 API 调用失败。

Chaining APIs：从任意 API 提交 Task 作业

提交地址

在 Cortex 集群内，任何 API（Realtime、Batch、Async、Task 均可）都可以通过 Istio Ingress Gateway 提交 Task 作业，统一地址为：

http://ingressgateway-operator.istio-system.svc.cluster.local/tasks/<api_name>

其中<api_name>是目标 Task API 的名字。请求体即 Task 作业提交载荷，例如：

import requests response = requests.post( "http://ingressgateway-operator.istio-system.svc.cluster.local/tasks/hello-world", json={"config": {"my_key": "my_value"}}, )

提交成功后，响应体中包含job_id，后续可用GET <endpoint>?jobID=<job_id>查询状态、DELETE <endpoint>?jobID=<job_id>停止作业（完整端点语义见 TaskAPI jobs）。这一能力让 Task API 天然适合作为 Airflow 等编排器的 task runner。

反向调用：Task API 调其他 API

如果你的 Task 容器需要反过来调用集群中的 Realtime、Batch 或 Async API，请参阅对应工作负载类型的 "Chaining APIs" 文档：

• Realtime API 文档（以及多版本分流场景下的 Traffic Splitter）；
• Batch API 文档；
• Async API 文档。

各工作负载的链式调用地址遵循相同的ingressgateway-operator.istio-system.svc.cluster.local/<kind>/<api_name>约定，仅在路径前缀上有所区分。

常见实战组合与注意事项

1. 参数化训练任务：把模型超参放进config，容器内读取/cortex/spec/job.json完成解析，无需为每次实验重新构建镜像。
2. Sidecar 模式：主容器写/mnt，辅助容器读取并上传日志或指标；两者共享同一生命周期，由 Pod 统一调度。
3. 流水线串联：Realtime API 收到请求后，通过/tasks/<api_name>提交耗时作业，并立即返回job_id；前端轮询 Task API 获取结果。
4. 版本一致性：容器镜像内安装的cortexCLI / Python 客户端务必与CORTEX_VERSION保持一致。
5. 入口约定：Task 容器通常不需要对外监听端口（CORTEX_PORT仅注入到非 Task 的 API 容器，见 pkg/workloads/k8s.go），入口逻辑应在command中声明并运行至完成。

参考文档

• Task API 总览
• Task API 配置参考
• TaskAPI jobs 提交与状态查询
• 容器与镜像规范
• 集群观测：日志 / 指标 / 告警

• 后端
• 云原生
• 模型推理服务
• MLOps
• 人工智能