在 ACK 上使用 Harbor CLI 进行 Agent 评测

安装 Harbor CLI

从 GitHub 克隆仓库并通过 pip 安装：

git clone https://github.com/alibaba/harbor.git
cd harbor
pip install -e .
harbor --version

配置 kubeconfig

Harbor ACK 环境通过 kubeconfig 连接集群。执行以下命令验证连接：

kubectl cluster-info

指定 context 或 kubeconfig 文件时，在 harbor run 命令中传入对应参数：

--ek context=my-ack-context
# 或
--ek kubeconfig=/path/to/kubeconfig

创建评测命名空间

评测相关资源（Trial Pod、Secret、PV/PVC 等）统一放在独立命名空间中：

kubectl create namespace harbor-eval

其他工具（可选）

• crane：用于验证推送到 ACR 的镜像（见步骤三）。

• ossutil：用于在命令行查看 OSS 中的评测结果文件（见查看评测结果文件）。

在集群内部署 BuildKit

集群内通常没有 Docker daemon，需部署 BuildKit 作为远程构建后端：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: buildkitd
  namespace: harbor-eval
spec:
  replicas: 1
  selector:
    matchLabels:
      app: buildkitd
  template:
    metadata:
      labels:
        app: buildkitd
    spec:
      containers:
        - name: buildkitd
          image: moby/buildkit:v0.15.0
          args:
            - --addr
            - tcp://0.0.0.0:1234
            - --config
            - /etc/buildkit/buildkitd.toml
          securityContext:
            privileged: true
          resources:
            requests:
              cpu: 500m
              memory: 1Gi
            limits:
              cpu: "2"
              memory: 4Gi
          volumeMounts:
            - name: buildkitd-config
              mountPath: /etc/buildkit/buildkitd.toml
              subPath: buildkitd.toml
            - name: registry-auth
              mountPath: /registry-auth/
      volumes:
        - name: buildkitd-config
          configMap:
            name: buildkitd-config
        - name: registry-auth
          secret:
            secretName: buildkitd-registry-auth
---
apiVersion: v1
kind: Service
metadata:
  name: buildkit-service
  namespace: harbor-eval
spec:
  type: ClusterIP
  selector:
    app: buildkitd
  ports:
    - port: 1234
      targetPort: 1234

配置 buildkitd 认证与镜像加速

BuildKit v0.15.0 不支持通过 CLI 参数配置 registry 认证，需通过配置文件设置。创建 buildkitd.toml ConfigMap：

apiVersion: v1
kind: ConfigMap
metadata:
  name: buildkitd-config
  namespace: harbor-eval
data:
  buildkitd.toml: |
    [registry."docker.io"]
      mirrors = ["mirror.gcr.io"]

    [registry."<YOUR-ACR-ADDRESS>"]
      config = "/registry-auth/"

其中，Docker Hub 镜像源设为 mirror.gcr.io：阿里云 Registry 镜像加速不支持代理第三方仓库（如 swebench），拉取时会返回 insufficient_scope 错误。

创建 ACR 认证 Secret（Docker config 格式）：

kubectl create secret generic buildkitd-registry-auth \
  --namespace=harbor-eval \
  --from-file=config.json=$HOME/.docker/config.json

批量构建并推送镜像

使用 harbor admin upload-images 命令扫描数据集中的所有 Task，逐个构建 Dockerfile 并推送到 ACR：

harbor admin upload-images \
  -t /path/to/dataset \
  -r <YOUR-ACR-ADDRESS> \
  --remote-buildkit tcp://buildkit-service:1234 \
  --update-config \
  --sanitize-image-names \
  --skip-unchanged \
  -n 4

命令执行流程：

1. 读取每个 Task 的 Dockerfile

2. 通过 buildctl 在远端 BuildKit 服务构建镜像

3. 推送到 ACR

4. 将 docker_image、built_content_hash、image_sha256 写回 task.toml

500 个 Task 在 -n 4 并行下约需 2~3 小时，建议使用 nohup ... & disown 执行，避免终端断开导致任务中断。

构建完成后验证镜像：

crane digest <YOUR-ACR-ADDRESS>/<image-name>:<tag>

task.toml 中的 docker_image 字段

upload-images 成功后，task.toml 的 [environment] 段会自动写入以下字段：

[environment]
docker_image = "registry.cn-hangzhou.aliyuncs.com/<ns>/harbor/<task-name>@sha256:..."
built_content_hash = "abc123..."
image_sha256 = "sha256:..."

harbor run 运行时，ACK 环境优先读取 docker_image 直接拉取镜像（秒级），而非集群内现场构建（分钟级）。

配置 ACR 拉取凭证

Trial Pod 从 ACR 拉取预构建镜像时需要认证。创建 docker-registry 类型的 Secret：

kubectl create secret docker-registry acr-pull-secret \
  --namespace=harbor-eval \
  --docker-server=registry.cn-hangzhou.aliyuncs.com \
  --docker-username=<账号> \
  --docker-password=<密码>

运行评测任务

以下命令在 ACK 集群中启动评测：Harbor 扫描数据集中的所有 Task，为每个 Task 创建 Trial Pod 并执行评测。-a 和 -m 请替换为实际使用的 Agent 和模型。

harbor run \
  -p ./my-dataset \
  --env ack \
  -n 1 \
  --ek namespace=harbor-eval \
  --ek registry=registry.cn-hangzhou.aliyuncs.com/<ns>/harbor \
  --ek image_pull_secret=acr-pull-secret \
  -a qwen-coder \
  -m qwen3.7-max \
  --no-delete \
  -y

常用参数说明：

指定节点调度

通过节点选择器将 Trial Pod 调度到特定机型，并覆盖资源配置：

harbor run \
  -p ./my-dataset \
  --env ack \
  -n 1 \
  --ek namespace=harbor-eval \
  --ek image_pull_secret=acr-pull-secret \
  --ek 'node_selector={"node.kubernetes.io/instance-type":"ecs.gn7i-c8g1.2xlarge"}' \
  --override-cpus 4 \
  --override-memory-mb 8192 \
  --override-gpus 1 \
  -a qwen-coder \
  -m qwen3.7-max \
  -y

过滤任务

通过以下参数筛选要运行的任务：

-i "task-prefix-*"   # 只运行名称匹配的任务
-x "skip-*"          # 排除名称匹配的任务
-l 10                # 最多运行 10 个任务

传递 Agent 环境变量

通过 --ae 参数将 API Key 等环境变量传入 Trial Pod，供 Agent 调用模型时使用：

--ae ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
--ae DASHSCOPE_API_KEY=$DASHSCOPE_API_KEY

使用 YAML 配置文件

参数较多时，将配置写入 YAML 文件集中管理：

# eval-config.yaml
dataset: ./my-dataset          # 或填写注册表引用

agent: qwen-coder
model: qwen3.7-max

environment:
  type: ack
  kwargs:
    namespace: harbor-eval
    registry: registry.cn-hangzhou.aliyuncs.com/<ns>/harbor
    image_pull_secret: acr-pull-secret
    service_account: harbor-eval-sa

n_concurrent_trials: 1

agent_env:
  - name: ANTHROPIC_API_KEY
    value: "${ANTHROPIC_API_KEY}"

harbor run -c eval-config.yaml -y

使用 ACS Sandbox 模式（可选）

在阿里云 Serverless 容器（ACS）上运行评测，或使用 OpenKruise SandboxSet 预热 Pod 加速 Trial 启动时，启用 Sandbox 模式。

SandboxClaim 模式依赖 OpenKruise CRD（agents.kruise.io/v1alpha1），启用前请确认集群已安装 OpenKruise，且 ServiceAccount 已具备相应的 CRD 权限（详见下文配置 RBAC）。

核心参数：

在 ACS 上运行示例：

harbor run \
  -p ./dataset \
  --env ack \
  -n 4 \
  --ek namespace=harbor-eval \
  --ek image_pull_secret=acr-pull-secret \
  --ek use_sandbox_claim=true \
  --ek sandboxset_replicas=4 \
  --ek 'sandbox_annotations={"k8s.aliyun.com/product-on-demand":"acs"}' \
  -a qwen-coder \
  -m qwen3.7-max \
  -y

如果不使用 Sandbox 模式，也可通过以下参数将标准 Trial Pod 调度到 virtual-kubelet 节点：

--ek 'node_selector={"type":"virtual-kubelet"}' \
--ek 'tolerations=[{"key":"virtual-kubelet.io/provider","operator":"Exists"}]'

配置 RBAC

Job Pod 需要通过 ServiceAccount 获得创建 Trial Pod 等操作的权限：

# harbor-eval-rbac.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: harbor-eval-sa
  namespace: harbor-eval
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: harbor-eval-role
  namespace: harbor-eval
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/exec", "pods/log"]
    verbs: ["get", "list", "create", "delete", "watch"]
  - apiGroups: [""]
    resources: ["configmaps", "secrets"]
    verbs: ["get", "list"]
  - apiGroups: ["batch"]
    resources: ["jobs"]
    verbs: ["get", "list", "create", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: harbor-eval-rolebinding
  namespace: harbor-eval
subjects:
  - kind: ServiceAccount
    name: harbor-eval-sa
    namespace: harbor-eval
roleRef:
  kind: Role
  name: harbor-eval-role
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f harbor-eval-rbac.yaml

使用 Sandbox 模式时，需为上述 Role 额外添加 sandboxsets、sandboxclaims、sandboxes 的 get/list/create/delete/watch 权限。

查看 Trial Pod 状态

# 查看所有 Trial Pod
kubectl get pods -n harbor-eval -l app=sandbox

# 查看特定 Pod 的日志
kubectl logs -n harbor-eval <pod-name> --tail=100

查看 Job 状态

使用 K8s Job 编排评测时，查看 Job 的执行状态和日志：

kubectl get jobs -n harbor-eval
kubectl describe job harbor-eval-job -n harbor-eval
kubectl logs -l job-name=harbor-eval-job -n harbor-eval --tail=200

查看评测结果文件

每个 Trial 的结果目录结构：

harbor-eval/
└── <task-name>/
    ├── agent/          # Agent 执行日志
    ├── verifier/       # Verifier 验证结果
    ├── artifacts/      # 任务产出物
    └── results.json    # 汇总结果

K8s Job 编排时，用 -o /mnt/oss/results 指定输出路径，结果经 OSS CSI fuse 直接写回 OSS，无需额外上传。评测完成后用 ossutil 查看：

ossutil ls oss://my-harbor-bucket/results/harbor-eval/

Pod 一直处于 Pending 状态

查看 Pod 事件：

kubectl describe pod <pod-name> -n harbor-eval

常见原因：

• 节点资源不足：调整 --override-cpus 或 --override-memory-mb

• 镜像拉取失败：检查 image_pull_secret 和 ACR 地址配置

• 节点选择器不匹配：确认 node_selector 中的标签在集群节点上存在

镜像拉取失败

# 确认 ACR 中存在目标镜像
docker manifest inspect <acr-address>/<image>:<tag>

# 确认 Secret 与 Pod 在同一命名空间
kubectl get secret acr-pull-secret -n harbor-eval

Harbor CLI 无法连接集群

# 验证 kubeconfig
kubectl cluster-info

# 在 Pod 内确认 RBAC 权限
kubectl auth can-i create pods -n harbor-eval --as=system:serviceaccount:harbor-eval:harbor-eval-sa

集群内运行时，kubeconfig 指向的 VPC 内网 IP 可能无法从 Pod CIDR 访问。将 API Server 地址改为集群内 Service 端点：https://kubernetes.default.svc:443。

评测任务超时

任务超时由 task.toml 中的以下字段控制：

[agent]
timeout_sec = 300

[verifier]
timeout_sec = 60

如需全局调整，使用顶层 CLI 参数（注意不是 --ek 参数）：

--agent-timeout-multiplier 2.0

docker_image 字段未生效

确认 Harbor CLI 版本不低于 0.6.5，旧版本不读取 docker_image 字段：

harbor --version