从 pipelines-components 运行 Ray Data Pipelines

下一版本的 Alauda AI Platform 将为 Kubeflow Pipelines 2.16.1 打包来自镜像 pipelines-components 项目的可复用组件。operator 可以预加载 AutoGluon pipelines。Ray Data 组是 实验性的,并且不会预加载。按照与其他自定义资产相同的方式进行编译:克隆 Alauda 提供的镜像,安装 kfp-components editable 版本,然后上传 YAML。请参阅 使用可复用的 Kubeflow Pipeline 组件。

Ray Data 本身不会作为 KFP 任务出现。parse_and_chunk 组件会提交一个 KubeRay RayJob。该作业会构建一个包含 PDF 路径的 ray.data 数据集,在 actor pool 中运行 Docling,并将每个文件对应的一个 JSONL 对象写入兼容 S3 的存储。

PDFs on an RWX PVC
        │  parse_and_chunk  (RayJob + Ray Data actor pool)
        ▼
JSONL chunks in S3  (source_file, chunk_index, text)
        │  ingest_to_milvus  (optional embedding InferenceService)
        ▼
Milvus collection
        │  download_model + model_deployment  (parallel with ingest)
        ▼
LLM InferenceService

编译并上传的 notebook 位于本页面旁:

如果只有几十个 PDF,请改为在 Workbench 中转换: 使用 Docling 和 SDG Hub 准备微调数据。 如需对分块和检索设置进行 RAG 搜索,请使用 使用 AutoRAG Pipelines 优化 RAG 应用。

先决条件

要求详细信息
Kubeflow Pipelines 2.16.1Alauda kfp-operator v26.3.1 或 DSPO v2.15.2。请参阅使用可复用的 Kubeflow Pipeline 组件。
KubeRay Operator集群插件。请参阅安装 KubeRay Operator。Pipeline ServiceAccount 必须能够在运行所在的命名空间中创建 rayjobs.ray.io。
WorkbenchStandard Data Science(Python 3.12),以便使用 kfp==2.16.1 进行编译。请参阅创建 Workbench。
RWX PVC用于保存输入 PDF。parse_and_chunk 会以只读方式将其挂载到 Ray head 和每个 worker。
兼容 S3 的存储桶用于保存中间分块 JSONL。创建一个包含 access_key 和 secret_key 键的 Secret(而不是 AWS_ACCESS_KEY_ID)。
Ray + Docling 镜像ray_image 必须已经包含 Ray 和 Docling。将其镜像到集群 registry。
可选,用于完整 RAG DAG一个可访问的 Milvus 2.4+ 服务、一个 Hugging Face token Secret(token)、一个模型缓存 PVC,以及传递给 llm_hardware_profile_namespace 的命名空间中的一个硬件配置。

组件运行时镜像默认为 ODH CPU datascience 镜像。将其替换为适用于集群的 Alauda 镜像,或在编译时设置 RELATED_IMAGE_RAG_BASE_RUNTIME。

Kueue:当命名空间具有 Local Queue 时,保留 bypass_kueue=false(默认值)。仅在没有 Kueue 的集群上设置 bypass_kueue=true。

准备输入存储

在 pipeline 命名空间中创建 PDF PVC 和分块存储 Secret:

NS=my-pipeline-namespace

kubectl -n "$NS" apply -f - <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-pvc
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 50Gi
EOF

kubectl -n "$NS" create secret generic minio-secret \
  --from-literal=access_key='<access-key>' \
  --from-literal=secret_key='<secret-key>'

将 PDF 复制到该 PVC 上的 input/pdfs/ 下(默认的 input_path)。挂载了 data-pvc 的 Workbench 可以从 JupyterLab 上传文件。系统会包含嵌套目录;num_files=0 会处理每个 *.pdf。

从 Workbench 编译

kfp-components 软件包未发布到 PyPI。克隆 Alauda 镜像仓库, 并在 Python 3.11 或更高版本的虚拟环境中安装。将 SDK 固定为 Alauda AI Platform 随附的 版本。将 <pipelines-components-repo-url> 替换为 Alauda 为该环境提供的 仓库地址:

git clone <pipelines-components-repo-url>
cd pipelines-components

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install 'kfp==2.16.1' 'kfp-kubernetes==2.16.1'
python -m pip install --no-deps -e .

如果只需要 JSONL 分块并打算自行生成嵌入,请仅编译 parse_and_chunk:

from kfp import compiler
from kfp_components.components.data_processing.parse_and_chunk import parse_and_chunk

compiler.Compiler().compile(
    parse_and_chunk,
    package_path="parse_and_chunk.yaml",
)

如果还需要 Milvus 数据导入和 LLM InferenceService,请编译完整的 RAG DAG。在运行时覆盖 ray_image 和 namespace,不要在此编译步骤中覆盖:

from kfp import compiler
from kfp_components.pipelines.data_processing.ray_data.pdf_documents_processing_rag_pipeline import (
    rag_multistep_pipeline,
)

compiler.Compiler().compile(
    rag_multistep_pipeline,
    package_path="rag_multistep_pipeline.yaml",
)

通过 Kubeflow Pipelines > Pipelines > Upload pipeline 上传 YAML,或 在同一 Workbench 中使用 KFP SDK 提交。

仅运行解析和分块

创建 parse_and_chunk 的运行并设置:

输入示例备注
pvc_namedata-pvc包含 PDF 的 RWX claim
pvc_mount_path/mnt/data必须与 RayJob 卷挂载一致
input_pathinput/pdfs相对于挂载路径
ray_image<registry>/mlops/docling-ray:<tag>Ray + Docling,已存在于集群中
namespacemy-pipeline-namespace与运行、PVC 和 Secret 位于同一命名空间
s3_endpointhttp://seaweedfs.mlops-demo-e2e:8333包含 scheme
s3_bucketrag-chunks如果不存在,则在首次写入时创建
s3_prefixchunks每个 PDF 一个 <stem>.jsonl
s3_secret_nameminio-secret键:access_key、secret_key
num_workers2Ray worker Pod;actors 必须能在这些 Pod 上运行
cpus_per_actor4Docling worker CPU;保持 OCR 关闭(作业会设置 do_ocr=False)
min_actors / max_actors2 / 4Ray Data ActorPoolStrategy
batch_size4每次 map_batches 调用处理的 PDF 数量
num_files00 表示所有 PDF
bypass_kueuefalse仅当命名空间没有 Local Queue 时使用 true

组件会等待 Ray 集群报告 readyWorkerReplicas == num_workers,然后等待 RayJob 的 jobStatus 变为 SUCCEEDED(最长 四小时)。输出为 URI s3://<bucket>/<prefix>。

每行 JSONL 的格式如下:

{"source_file": "policy.pdf", "chunk_index": 0, "text": "..."}

tokenizer 应与之后使用的嵌入模型一致。默认值为 sentence-transformers/all-MiniLM-L6-v2。对于完整的 RAG pipeline,请传入与 embedding_model 相同的字符串。

不要将 Docling actors 调度到 Ray head 上。调整 cpus_per_actor × max_actors,使资源池能够容纳在 worker 组中;如果转换器挂起,会在 timeout_seconds 后于子进程内终止。

运行完整的 RAG pipeline

已编译的 rag_multistep_pipeline 包含两个相互独立的链:

  1. parse_and_chunk → ingest_to_milvus(可选先运行 deploy_embedding_model)
  2. download_model → model_deployment

保留 deploy_embedding=false 和 embedding_endpoint="",以便在 ingest task 中使用本地 sentence-transformers 模型进行嵌入。只有在需要专用嵌入 InferenceService 时,才设置 deploy_embedding=true。

模型链的其他运行输入:

输入示例说明
hf_secret_namehf-token-secret键必须为 token
llm_model_name集群允许拉取的模型 ID缓存于 model_cache_pvc
model_cache_pvcmodel-cache-pvc在运行前创建
llm_hardware_profile_namegpu-profile必须存在
llm_hardware_profile_namespace保存 Hardware Profile 的 namespace使用此集群中的 Hardware Profile namespace
milvus_hostmilvus.milvus.svc.cluster.local集群内 DNS,不含 scheme
drop_existingtrue重新创建 collection

ingest_to_milvus 从同一个 minio-secret 中读取 S3_ACCESS_KEY / S3_SECRET_KEY。LLM 部署步骤不会等待 ingest;两个链可以 独立完成。

Ray Data 在作业内的处理方式

parse_and_chunk 注入 RayJob 的入口点是 Ray Data pipeline:

ds = ray.data.from_pandas(pd.DataFrame({"path": pdf_paths}))
ds = ds.repartition(max_actors * 10)
results = ds.map_batches(
    DoclingChunkProcessor,
    compute=ray.data.ActorPoolStrategy(min_size=min_actors, max_size=max_actors),
    batch_size=batch_size,
    batch_format="numpy",
    num_cpus=cpus_per_actor,
)

DoclingChunkProcessor 是一个 Ray actor。每个 actor 都拥有一个子进程,该子进程运行 DocumentConverter + HybridChunker 并上传 JSONL。超时会重启该 子进程,因此单个卡住的 PDF 不会导致 actor 终止。这与 Workbench Docling 指南针对数千个文件介绍的模式相同;使用此组件时,无需自行编写此脚本。

该 actor 池形态的纯 CPU 冒烟测试(不使用 Docling,也不使用 PDF PVC)位于 assets/ray-data-pipelines/rayjob-smoke.yaml。

故障排除

症状原因
RayJob 保持为 Pending / Suspended缺少 Kueue Local Queue,或 bypass_kueue 仍为 false。
Ray cluster did not become readyWorker 的 CPU/内存请求超过 namespace 配额,或无法拉取 ray_image。
No PDFs found文件不在 <pvc_mount_path>/<input_path>/**/*.pdf 下。
S3 403 / 缺少凭据Secret 键必须为 access_key 和 secret_key。AutoGluon loader 使用不同的键名。
在 Workbench 中本地转换时发生 OOM将作业移到此处;单个 Docling actor 需要数 GB 内存和多个 CPU。
model_deployment 无法绑定 GPUllm_hardware_profile_name / namespace 与活动的 Hardware Profile 不匹配。
Ingest 失败并生成空集合parse_and_chunk 未写入任何对象;检查 RayJob 日志中的 timeout / empty 行。

后续步骤