云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载本篇技术指南讲解 Olares开源个人云操作系统中recommend类型应用 Chart 的核心配置方法开发者主要通过templates/目录下的embedding.yaml、prerank.yaml、rank.yaml、train.yaml四个模板文件把推荐算法流程编排为 Argo Workflows 的CronWorkflow定时流水线。读完本文你将掌握推荐应用 Chart 的目录结构、四个工作流模板的每个字段含义与取值策略并理解运行时这些值如apiUrl、userspace.appData是如何由 Olares 应用服务框架注入的可直接照此编写可部署的 Recommend 应用 Chart。一、Recommend 应用与模板文件概览在 Olares 的应用体系中recommend是一种以“推荐工作流”为核心的应用类型。与常规的 Web 应用不同它并不直接对外提供界面服务而是通过一系列定时执行的数据处理任务来完成推荐链路例如定期对用户做向量化embedding、召回recall、粗排prerank、精排rank甚至模型训练train。从源码结构看Olares 应用服务框架在 constants.go 中仍保留了recommend作为合法的资源类型ResourceTypes集合包含app、recommend、model、agent、middleware并且在 scaffold.go 的Options.Type注释里也保留了对recommend类型的支持。注意在最新的 OlaresManifest 规范0.12.0中recommend已不再作为独立的应用类型出现在规范字段里见 manifest.md但既有 Recommend 应用 Chart 的模板组织方式仍然沿用本文所述的四个文件约定。若你正在维护历史 Recommend 应用请同步关注 OlaresManifest 版本升级要求。创建recommend应用 Chart 时需要重点配置templates/目录下的四个文件embedding.yaml—— 用户/内容向量化定时任务prerank.yaml—— 召回 粗排流水线rank.yaml—— 特征提取 精排流水线train.yaml—— 模型训练定时任务。这四个文件均为apiVersion: argoproj.io/v1alpha1、kind: CronWorkflow的 Kubernetes 资源由 Argo Workflows 控制器调度执行。整个 Chart 的目录结构遵循标准的 Olares Application Chart 结构Chart.yaml、OlaresManifest.yaml、templates/、values.yaml等。二、四个模板的公共结构与字段说明四个模板文件的骨架完全一致外层是CronWorkflow的调度与生命周期策略内层是workflowSpec描述的实际执行步骤。下表完整列出embedding.yaml示例中出现的关键字段及其含义其他三个文件中的同名字段语义相同。字段说明apiVersion使用的 API 版本此处固定为argoproj.io/v1alpha1。kind定义了一个CronWorkflow对象。metadata.nameCronWorkflow的名称示例中按功能-应用名命名如user-embedding-r4sport。metadata.namespaceCronWorkflow所属命名空间示例中使用 Helm 模板值{{ .Release.Namespace }}。spec.scheduleCron 表达式定义CronWorkflow的调度时间。spec.startingDeadlineSeconds启动截止时间表示从计划调度时刻起允许的最大延迟秒数超过则本次不再执行。spec.concurrencyPolicy并发策略规定下一个调度时刻到来时如何处理当前正在运行的作业Replace表示用新作业替换旧作业Forbid表示禁止并发、跳过本次。spec.successfulJobsHistoryLimit成功作业历史记录保留条数上限。spec.failedJobsHistoryLimit失败作业历史记录保留条数上限。spec.suspend是否暂停CronWorkflow的运行false表示正常调度执行。spec.ttlStrategy.secondsAfterSuccess作业成功后保留的存活时间秒。spec.ttlStrategy.secondsAfterCompletion作业完成后保留的存活时间秒。spec.ttlStrategy.secondsAfterFailure作业失败后保留的存活时间秒。spec.workflowSpec.entrypointWorkflow 的入口模板名称即流水线从哪个模板开始执行。spec.workflowSpec.volumes[0].name卷定义示例中命名为huggingface。spec.workflowSpec.volumes[0].hostPath.type宿主机路径类型示例使用DirectoryOrCreate指定目录不存在则创建。spec.workflowSpec.volumes[0].hostPath.path宿主机上的实际路径示例引用{{ .Values.userspace.appData }}/rss/model/huggingface。spec.workflowSpec.templates[0].nameWorkflow 模板名称。spec.workflowSpec.templates[0].steps[0][0].name步骤定义及其名称。spec.workflowSpec.templates[0].steps[0][0].template该步骤引用的模板名称。spec.workflowSpec.templates[1].name第二个模板容器执行模板的名称。spec.workflowSpec.templates[1].container.image容器镜像名称。spec.workflowSpec.templates[1].container.imagePullPolicy镜像拉取策略示例统一使用Always。spec.workflowSpec.templates[1].container.env[0].name环境变量定义及其名称。spec.workflowSpec.templates[1].container.env[0].value环境变量的值。spec.workflowSpec.templates[1].container.env[1].name第二个环境变量的名称。spec.workflowSpec.templates[1].container.env[1].value第二个环境变量的值。spec.workflowSpec.templates[1].container.volumeMounts[0].mountPath挂载路径定义。spec.workflowSpec.templates[1].container.volumeMounts[0].name所挂载卷的名称。各模板在字段取值上的差异正是推荐流水线不同环节的调度策略与存储依赖的体现下文逐文件展开。三、embedding.yaml用户嵌入定时任务embedding.yaml负责用户/内容向量化的定时执行。示例中的完整配置如下apiVersion: argoproj.io/v1alpha1 kind: CronWorkflow metadata: name: user-embedding-r4sport namespace: {{ .Release.Namespace }} spec: schedule: 0 */1 * * * startingDeadlineSeconds: 0 concurrencyPolicy: Replace successfulJobsHistoryLimit: 1 failedJobsHistoryLimit: 1 suspend: false ttlStrategy: secondsAfterSuccess: 3600 secondsAfterCompletion: 3600 secondsAfterFailure: 3600 workflowSpec: entrypoint: userEmbeddingFlow volumes: - name: huggingface hostPath: type: DirectoryOrCreate path: - {{ .Values.userspace.appData }}/rss/model/huggingface templates: - name: userEmbeddingFlow steps: - - name: user-embedding template: user-embedding-template - name: user-embedding-template container: image: beclab/r4userembedding imagePullPolicy: Always env: - name: KNOWLEDGE_BASE_API_URL value: {{ .Values.apiUrl }} - name: TERMINUS_RECOMMEND_SOURCE_NAME value: r4sport volumeMounts: - mountPath: /root/.cache/huggingface name: huggingface该文件的关键设计点调度节奏schedule: 0 */1 * * *表示每小时整点执行一次。考虑到向量化计算对 CPU/内存占用较高且需要读取全量用户数据通常以小时为粒度而非像粗排、精排那样几分钟一次。并发策略concurrencyPolicy: Replace如果上一轮嵌入任务尚未结束而新一轮调度到来直接替换为新一轮作业避免历史任务堆积。历史记录与 TTL成功/失败历史各保留 1 条作业结束后 3600 秒1 小时自动清理防止CronWorkflow积累大量已完成的工作流记录。HuggingFace 缓存卷嵌入任务使用大模型做向量化时需要缓存 HuggingFace 模型权重。这里通过hostPath卷把宿主机目录{{ .Values.userspace.appData }}/rss/model/huggingface挂载进容器/root/.cache/huggingface使模型权重在多次调度之间复用避免每次重复下载。环境变量KNOWLEDGE_BASE_API_URL知识库 API 地址运行时由框架注入见第六节嵌入任务从中读取用户/内容数据TERMINUS_RECOMMEND_SOURCE_NAME推荐源名称示例为r4sport用于标识数据来源多个推荐源在同一集群内可通过该变量区分。流水线组织入口模板userEmbeddingFlow只有一个步骤user-embedding引用容器模板user-embedding-template。这是最简的“单步骤”流水线写法。四、prerank.yaml召回与粗排流水线prerank.yaml是推荐链路中最核心的定时流水线包含**召回recall与粗排prerank**两个串行阶段示例完整配置如下apiVersion: argoproj.io/v1alpha1 kind: CronWorkflow metadata: name: prerank-r4sport namespace: {{ .Release.Namespace }} spec: schedule: */5 * * * * startingDeadlineSeconds: 0 concurrencyPolicy: Replace successfulJobsHistoryLimit: 1 failedJobsHistoryLimit: 1 suspend: false ttlStrategy: secondsAfterSuccess: 3600 secondsAfterCompletion: 3600 secondsAfterFailure: 3600 workflowSpec: entrypoint: algorithm volumes: - name: nfs hostPath: type: DirectoryOrCreate path: - {{ .Values.userspace.appData }}/rss/data - name: juicefs hostPath: type: DirectoryOrCreate path: - {{ .Values.userspace.appData }}/rss/data templates: - name: algorithm steps: - - name: recall template: recall-template - - name: prerank template: prerank-template - name: recall-template container: image: beclab/r4recall:v0.0.5 imagePullPolicy: Always env: - name: KNOWLEDGE_BASE_API_URL value: {{ .Values.apiUrl }} - name: NFS_ROOT_DIRECTORY value: /nfs - name: JUICEFS_ROOT_DIRECTORY value: /juicefs - name: ALGORITHM_FILE_CONFIG_PATH value: /usr/config/ - name: TERMINUS_RECOMMEND_SOURCE_NAME value: r4sport - name: SUPPORT_LANGUAGE value: en - name: SUPPORT_TIMELINESS value: 0 - name: SYNC_PROVIDER value: bytetrade - name: SYNC_FEED_NAME value: sport - name: SYNC_MODEL_NAME value: bert_v2 volumeMounts: - mountPath: /nfs name: nfs - mountPath: /juicefs name: juicefs - name: prerank-template container: image: beclab/r4prerank:v0.0.5 imagePullPolicy: Always env: - name: KNOWLEDGE_BASE_API_URL value: {{ .Values.apiUrl }} - name: NFS_ROOT_DIRECTORY value: /nfs - name: JUICEFS_ROOT_DIRECTORY value: /juicefs - name: ALGORITHM_FILE_CONFIG_PATH value: /usr/config/ - name: TERMINUS_RECOMMEND_SOURCE_NAME value: r4sport - name: SUPPORT_LANGUAGE value: en - name: SUPPORT_TIMELINESS value: 0 volumeMounts: - mountPath: /nfs name: nfs - mountPath: /juicefs name: juicefs关键设计点调度节奏与并发schedule: */5 * * * *每 5 分钟一次配合concurrencyPolicy: Replace。推荐结果需要周期性刷新但又不希望上一轮未完成的召回/粗排阻塞新一轮执行。串行步骤组织入口模板algorithm把recall与prerank写成两个顺序执行的步骤组两个- -列表项之间是串行关系即先召回、后粗排粗排依赖召回的中间结果。双数据卷设计nfs与juicefs两个卷在示例中挂载到同一宿主目录{{ .Values.userspace.appData }}/rss/data但容器内挂载点不同/nfs与/juicefs。这种“同一物理目录、双挂载点”的写法从源码结构看是为了让算法容器以统一的环境变量NFS_ROOT_DIRECTORY、JUICEFS_ROOT_DIRECTORY访问数据便于同一套算法代码适配不同存储后端。召回阶段recall-template镜像beclab/r4recall:v0.0.5的环境变量最丰富除通用变量外还包括ALGORITHM_FILE_CONFIG_PATH/usr/config/算法配置文件目录SUPPORT_LANGUAGEen支持的语言SUPPORT_TIMELINESS0时效性支持开关字符串0表示关闭SYNC_PROVIDERbytetrade数据同步提供方SYNC_FEED_NAMEsport同步的 feed 名称SYNC_MODEL_NAMEbert_v2使用的向量模型标识。粗排阶段prerank-template镜像beclab/r4prerank:v0.0.5只需基础环境变量知识库地址、存储目录、算法配置路径、推荐源、语言与时效性因为粗排输入来自召回结果无需再配置同步类变量。五、rank.yaml特征提取与精排流水线rank.yaml负责精排先从知识库提取特征extractor再执行精排模型rank。示例完整配置如下apiVersion: argoproj.io/v1alpha1 kind: CronWorkflow metadata: name: rank-r4sport namespace: {{ .Release.Namespace }} spec: schedule: */5 * * * * startingDeadlineSeconds: 0 concurrencyPolicy: Forbid successfulJobsHistoryLimit: 1 failedJobsHistoryLimit: 1 suspend: false ttlStrategy: secondsAfterSuccess: 3600 secondsAfterCompletion: 3600 secondsAfterFailure: 3600 workflowSpec: entrypoint: rankFlow volumes: - name: model hostPath: type: DirectoryOrCreate path: - {{ .Values.userspace.appData }}/rss/model templates: - name: rankFlow steps: - - name: extractor template: extractor-template - - name: rank template: rank-template - name: extractor-template container: image: beclab/r4extractor:v0.0.5 imagePullPolicy: Always env: - name: KNOWLEDGE_BASE_API_URL value: {{ .Values.apiUrl }} - name: TERMINUS_RECOMMEND_SOURCE_NAME value: r4sport volumeMounts: - mountPath: /opt/rank_model name: model - name: rank-template container: image: beclab/r4rank imagePullPolicy: Always env: - name: KNOWLEDGE_BASE_API_URL value: {{ .Values.apiUrl }} - name: TERMINUS_RECOMMEND_SOURCE_NAME value: r4sport volumeMounts: - mountPath: /opt/rank_model name: model关键设计点并发策略与粗排不同这里使用concurrencyPolicy: Forbid。精排阶段计算密集跑排序模型若上一轮尚未结束直接跳过新一轮调度更合理避免多个精排作业同时争抢模型卷与计算资源。模型卷model卷把{{ .Values.userspace.appData }}/rss/model挂载到容器内/opt/rank_model供特征提取与精排两个阶段共享精排模型文件。注意该目录与 embedding 使用的模型缓存目录.../rss/model/huggingface同属rss/model下按子目录区分。两阶段串行入口模板rankFlow先执行extractor-template镜像beclab/r4extractor:v0.0.5特征提取再执行rank-template镜像beclab/r4rank精排打分。两个模板的环境变量均为KNOWLEDGE_BASE_API_URL与TERMINUS_RECOMMEND_SOURCE_NAME——精排阶段的数据输入输出都经由知识库 API 交换模型文件则通过共享卷传递。六、train.yaml模型训练模板train.yaml用于模型训练场景。原文档给出的示例与rank.yaml完全一致此处原文完整保留apiVersion: argoproj.io/v1alpha1 kind: CronWorkflow metadata: name: rank-r4sport namespace: {{ .Release.Namespace }} spec: schedule: */5 * * * * startingDeadlineSeconds: 0 concurrencyPolicy: Forbid successfulJobsHistoryLimit: 1 failedJobsHistoryLimit: 1 suspend: false ttlStrategy: secondsAfterSuccess: 3600 secondsAfterCompletion: 3600 secondsAfterFailure: 3600 workflowSpec: entrypoint: rankFlow volumes: - name: model hostPath: type: DirectoryOrCreate path: - {{ .Values.userspace.appData }}/rss/model templates: - name: rankFlow steps: - - name: extractor template: extractor-template - - name: rank template: rank-template - name: extractor-template container: image: beclab/r4extractor:v0.0.5 imagePullPolicy: Always env: - name: KNOWLEDGE_BASE_API_URL value: {{ .Values.apiUrl }} - name: TERMINUS_RECOMMEND_SOURCE_NAME value: r4sport volumeMounts: - mountPath: /opt/rank_model name: model - name: rank-template container: image: beclab/r4rank imagePullPolicy: Always env: - name: KNOWLEDGE_BASE_API_URL value: {{ .Values.apiUrl }} - name: TERMINUS_RECOMMEND_SOURCE_NAME value: r4sport volumeMounts: - mountPath: /opt/rank_model name: model需要特别说明原文档中train.yaml的示例内容与rank.yaml完全相同metadata.name同为rank-r4sport、入口同为rankFlow、模板与镜像一致。可以推断这份示例的实际定位是训练模板的占位起点供开发者在此基础上替换为真正的训练流水线。若你要将其用于训练至少应从以下几个维度改造名称与入口将metadata.name改为体现训练语义的名称如train-r4sport并新增/修改入口模板与步骤例如增加数据采样、训练、模型导出等阶段让训练逻辑与精排逻辑解耦镜像与调度把beclab/r4extractor、beclab/r4rank替换为训练镜像如数据准备、模型训练镜像训练任务通常计算密集且耗时较长可适当放宽schedule频率、延长startingDeadlineSeconds或调整concurrencyPolicyForbid仍是避免训练作业并发冲突的合理选择模型卷挂载点训练产出模型后应写入模型卷供 embedding/prerank/rank 使用示例中挂载/opt/rank_model的写法可保持实际训练镜像需与精排阶段约定同一模型目录。总之train.yaml需要开发者按实际训练流程自行落地切勿直接照搬rank.yaml部署。七、运行时值注入apiUrl 与 userspace.appData 的来源四个模板中反复出现两个 Helm 模板变量{{ .Values.apiUrl }}与{{ .Values.userspace.appData }}。它们不是由 Chart 作者在values.yaml里硬编码的而是在应用安装时由 Olares 应用服务框架动态注入的。在 workflowinstaller/installer.go 的getSettings中可以看到完整的注入逻辑apiUrl被设置为http://knowledge-base-api.user-system-用户名:3010指向当前用户命名空间下的知识库 API 服务这正是四个模板中KNOWLEDGE_BASE_API_URL的运行时取值来源userspace.appData来自用户空间 bfl StatefulSet 的注解与宿主机路径拼接user-space-用户名命名空间下bfl工作负载的appcache_hostpath注解以及userspace_hostpath注解下的Data子目录其读取逻辑见 installer.go注入与否取决于 Chart 中OlaresManifest.yaml的permission.appData/permission.appCache/permission.userData声明——只有声明了对应权限userspace下才会出现相应键值getSettings中按Cfg.Permission.AppData等字段逐个判断。这与 manifest.md 中关于permission段的说明完全一致。也就是说模板中的hostPath指向的是用户空间内的真实持久化目录工作流容器通过挂载这些目录实现了推荐数据与模型在多次调度之间的持久化复用。Chart 作者无需、也不应把这些路径写死。八、安装与生命周期Recommend 工作流如何被管理Recommend 应用并不走常规应用的 Deployment 安装路径而是由 app-service 的专用安装处理器驱动。在 handler_installer_install_recommend.go 的installRecommend中可以看到完整流程从请求读取应用名与仓库地址RepoURL调用getWorkflowConfigFromRepo下载 Chart 并解析出工作流配置见 utils.go校验 Chart 声明的中间件依赖是否满足创建ApplicationManagerType: Recommend并置为Installing状态调用workflowinstaller.Install通过 Helm 客户端把 Chart 安装进{{ .Release.Namespace }}随后调用 argo/workflow.go 的UpdateWorkflowInNamespace为命名空间内所有CronWorkflow打上workflows.argoproj.io/controller-instanceid固定值knowledge-shared、workflows.app.bytetrade.io/owner、applications.app.bytetrade.io/need_cluster_scoped_app等标签并在命名空间上记录工作流名称与标题注解从而把 Helm 渲染出的CronWorkflow纳入 Argo 控制器与 Olares 生命周期管理卸载时uninstallRecommend会先清理知识库入口数据并通知知识服务再卸载 Helm Release 并删除命名空间升级走upgradeRecommend同样先下载最新 Chart 再执行workflowinstaller.Upgrade。因此Chart 作者只需要保证templates/下四个文件能通过 Helm 渲染出合法的CronWorkflow剩余的标签标注、命名空间归属与生命周期协调均由框架完成。九、编写 Recommend Chart 的实践要点综合以上分析编写一个可运行的 Recommend 应用 Chart 时建议遵循以下要点四文件齐备embedding.yaml、prerank.yaml、rank.yaml、train.yaml缺一不可即使某环节暂不需要也建议保留占位模板并配合suspend: true暂停调度。按环节选择并发策略计算轻、需持续刷新的环节embedding、prerank用Replace防止堆积计算重、模型共享的环节rank、train用Forbid避免并发冲突。统一使用框架注入的模板变量数据路径一律通过{{ .Values.userspace.appData }}派生如.../rss/data、.../rss/model、.../rss/model/huggingface知识库地址一律使用{{ .Values.apiUrl }}不要在模板中硬编码路径或 IP。用TERMINUS_RECOMMEND_SOURCE_NAME区分推荐源同一集群内可部署多个 Recommend 应用靠该变量隔离各自的数据与模型目录示例中的r4sport即体育内容推荐源。结合 OlaresManifest 声明权限务必在OlaresManifest.yaml中声明permission.appData等字段否则userspace.appData不会被注入参考 manifest.md同时留意最新规范中recommend类型已不再被列举历史应用升级前需核对 manifest 版本兼容性。模型缓存共享将 HuggingFace 缓存、精排模型分别规划在rss/model下的独立子目录embedding 与 rank 阶段各挂载所需子目录避免重复下载与相互覆盖。按上述方式组织的 Recommend Chart即可被 Olares 应用服务框架识别、安装并纳入 Argo 定时调度体系形成“每小时向量化、每 5 分钟召回粗排、每 5 分钟精排、定期训练”的完整推荐闭环。赞分享云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载相关推荐Argo Workflows 使用 argo cron create 命令创建 CronWorkflow 定时工作流Argo Workflows 使用 argo cron create 命令创建 CronWorkflow 定时工作流 argo cron create 是 Ar云原生容器编排工作流自动化任务调度后端Argo Workflows 集群工作流模板更新指南argo cluster-template update 命令详解Argo Workflows 集群工作流模板更新指南argo cluster template update 命令详解 argo cluster templa云原生容器编排工作流自动化任务调度后端Argo Workflows 使用指南argo cron get 命令详解——查看 CronWorkflow 运行详情Argo Workflows 使用指南 argo cron get 命令详解——查看 CronWorkflow 运行详情 argo cron get 是 Ar云原生容器编排工作流自动化任务调度后端上一篇蓝鲸 CMDB 关联关系体系 API 实战关联类型、模型关联与实例关联的增删改查下一篇从零开始训练Vosk语音模型打造专属离线语音识别系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考