Deepgram Self-Hosted Helm Chart 演进全解从 0.1.0-alpha 到 0.24.0 的功能开关、弹性伸缩与生产运维实践【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend本文以仓库中 nova-3 版本的 CHANGELOG.md 为主线结合同目录下的 values.yaml、README.md 与 Chart.yaml完整梳理 Deepgram 自托管 Helm Chart 从 2024 年 5 月首个 alpha 版本到 2025 年 11 月 v0.24.0 的功能演进脉络。读者将掌握该 Chart 的版本与镜像发布节奏、Nova-3 相关 NER 功能开关、Service 网络暴露模型、Pod/节点双层弹性伸缩、Voice Agent 内置支持、模型持久化与 License Proxy 高可用等关键配置体系并能在自有 Kubernetes 集群上完成安装、升级与回滚。一、Chart 定位与当前基线deepgram-self-hosted是一个用于在自托管 Kubernetes 环境中运行 Deepgram 语音服务STT、TTS、Voice Agent的 Helm Chart。仓库内维护了两套版本线nova-2/与nova-3/本文聚焦于 nova-3 目录。从 Chart.yaml 可以看到当前基线chart 版本0.24.0application 类型appVersionrelease-251118即 2025 年 11 月 18 日发布的 Deepgram 自托管容器镜像Kubernetes 兼容性1.28.0-0内置依赖NVIDIAgpu-operator^24.3.0、cluster-autoscaler^9.37.0、kube-prometheus-stack^60.2.0、prometheus-adapter^4.10.0Chart 模板按组件划分位于 templates 目录api/API 组件的 Deployment、HPA、Ingress、RBAC、Service 等模板如 api.deployment.yaml、api.hpa.yamlengine/Engine 推理组件的 Deployment、HPA、RBAC、Service 等模板license-proxy/可选 License Proxy 组件模板volumes/AWS EFS、GCP GPD 等模型存储卷模板。同时仓库提供 samples 目录 下的三份基准部署示例01-basic-setup-aws.values.yaml、01-basic-setup-aws.cluster-config.yaml、02-basic-setup-gcp.yaml 与 03-basic-setup-onprem.yaml覆盖 AWS EKS、GCP GKE 与自建集群三种场景此外 dev_omi_values.yaml 与 prod_omi_values.yaml 展示了本项目对 Chart 的实际生产 overlay 用法GKE 部署的详细步骤可参考 how_to_deploy_deepgram_self_hosted_on_gke.md。二、月度镜像发布节奏容器标签如何随版本滚动CHANGELOG 中占比最大的变更类型是默认容器标签的月度更新。Chart 的appVersion与各组件image.tag始终跟踪 Deepgram 自托管容器镜像的发布节奏典型模式为release-YYMMDD。从 CHANGELOG 可还原出完整时间线Chart 版本发布日期默认镜像标签0.24.02025-11-18release-2511180.23.02025-10-29release-2510290.22.02025-10-15release-2510150.21.02025-09-29release-2509290.19.02025-09-12release-2509120.18.02025-08-28release-2508280.17.02025-08-14release-2508140.16.02025-07-31release-2507310.15.02025-07-10release-2507100.14.02025-06-26release-2506260.13.02025-06-10release-2506100.12.02025-03-31release-2503310.11.02025-03-07release-2503070.10.02025-01-30release-2501300.9.02024-12-26release-2412260.8.02024-11-21release-2411210.7.02024-10-24release-2410240.6.02024-09-27release-2409270.5.02024-08-27release-2408270.4.02024-07-25release-240725在 values.yaml 中三个组件的镜像路径与标签分别位于api.image、engine.image、licenseProxy.image当前默认值均为release-251118镜像来自quay.io/deepgram/self-hosted-api、quay.io/deepgram/self-hosted-engine、quay.io/deepgram/self-hosted-license-proxypullPolicy默认IfNotPresent。如果已将镜像导入私有仓库可通过修改image.path指向私有镜像源。按 README.md 的标准升级流程升级时只需更新各image.tag后执行helm upgrade -f my-values.yaml [RELEASE_NAME] deepgram/deepgram-self-hosted --atomic --timeout 60m回滚则使用helm rollback deepgram值得注意的镜像相关演进还包括0.7.0 引入的streaming WebSocket TTS属于纯软件特性无需新增 TTS 模型0.7.0 同时将 AWS 示例迁移到内置 NVIDIA 驱动与工具链的EKS accelerated AMI不再依赖 GPU Operator 安装驱动0.6.0 起 Engine 容器支持运行期模型自动加载——对不支持inotify的文件系统如 NFS/CSI 挂载的 PersistentVolume模型加载/卸载不再需要重启 Pod。三、Nova-3 模型时代的 NER 功能开关演进CHANGELOG 中一条清晰的主线是围绕 Nova-3 模型的命名实体识别NER与格式化能力的默认行为演进这在 values.yaml 的api.features与engine.features中有完整落点版本变更当前默认值0.4.0为 API 容器引入实体检测开关默认关闭api.features.entityDetection: false0.5.0预录音频英语实体检测/增强型脱敏达到 GA—0.11.1开放配置以启用 NER 模型—0.19.0api.features.formatEntityTags与engine.features.streamingNer默认改为trueNova-3 模型必需true/true0.22.0api.features.entity_redaction默认开启存在有效 NER 模型时自动启用脱敏api.features.entityRedaction: true对应到当前 values.yaml 的完整功能开关集为api: features: entityDetection: false # 预录音频实体检测需有效实体检测模型 entityRedaction: true # 基于实体的脱敏需有效实体检测模型 formatEntityTags: true # 预录音频实体标签格式化需有效 NER 模型 redactUsage: true # 使用量元数据脱敏 listenV2: false # Flux 轮转式流式 STT diskBufferPath: # 高负载时请求队列落盘缓冲路径避免 OOM engine: features: streamingNer: true # 流式音频实体标签格式化需有效 NER 模型 useV2LanguageDetection: false # 36 语言检测模型0.24.0 新增的use_v2_language_detection功能开关对应 values 中的engine.features.useV2LanguageDetection默认关闭用于启用36 语言检测模型是 v0.24.0 相对早期版本在语种覆盖能力上的重要升级。此外 0.22.0 新增的redactUsage默认开启用于对使用量元数据进行脱敏属于隐私治理层面的默认安全项。四、Service 暴露模型从 NodePort 到 ClusterIP 的默认策略转变v0.20.0 是网络配置的分水岭。该版本为 API、Engine、License Proxy 三组服务统一引入了可配置的 Service 类型并将默认类型从 NodePort 改为 ClusterIP同时新增service.annotationsLoadBalancer 类型下的服务注解service.loadBalancerSourceRanges按 IP CIDR 白名单限制 LoadBalancer 访问来源service.externalTrafficPolicy控制外部流量路由策略Cluster或Local。在 values.yaml 中三组服务均以相同结构呈现以 API 为例api: service: type: ClusterIP # ClusterIP | NodePort | LoadBalancer annotations: {} # 仅 LoadBalancer 生效 loadBalancerSourceRanges: [] # 仅 LoadBalancer 生效 externalTrafficPolicy: # Cluster | LocalREADME 给出了生产场景的安全配置范例——API 服务使用 AWS NLB 并限制来源网段、保留源 IPapi: service: type: LoadBalancer annotations: service.beta.kubernetes.io/aws-load-balancer-type: nlb service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing loadBalancerSourceRanges: - 10.0.0.0/8 # 允许私有网络访问 - 192.168.1.0/24 # 允许指定子网访问 externalTrafficPolicy: Local # 保留源 IP 并减少转发跳数externalTrafficPolicy的语义Cluster默认将流量路由到集群任意节点再转发至目标 PodLocal仅路由到运行目标 Pod 的节点可保留客户端源 IP适合对审计与真实来源有要求的场景。五、弹性伸缩体系节点伸缩与 Pod 伸缩双层设计弹性能力从早期版本就开始建设v0.2.0-beta 引入cluster-autoscaler节点自动伸缩与 Deepgram 组件的 Pod 自动伸缩并支持 License Server 备份机制v0.8.1 修正了 Prometheus Adapter Chart 的默认比率指标统一为 0.0~1.0 标度v0.18.1 修复了 API/Engine Deployment 在开启自动伸缩时硬编码 replicas 与 HPA 冲突的问题v0.23.0 将cluster-autoscaler升级到 9.52.1、prometheus-adapter升级到 4.14.2。5.1 手动副本数与配置迁移早期版本使用scaling.static.{api,engine}.replicasv0.2.0-beta 将其迁移为scaling.replicas.{api,engine}。当前 values.yaml 中scaling: replicas: api: 1 engine: 1 # 开启 Voice Agent 时可按引擎类型分别指定副本数 auto: enabled: false # 开启 Pod 自动伸缩5.2 Engine 的硬限与软限两种伸缩策略README 对 Engine 自动伸缩给出了非常清晰的两种模式硬限模式同时配置engine.concurrencyLimit.activeRequests与scaling.auto.engine.metrics.requestCapacityRatio。activeRequests为单 Engine Pod 可承载的硬性请求数上限requestCapacityRatio决定可用请求槽位填充到什么比例时扩容例如 0.8 表示活跃请求达到并发上限的 80% 时扩容。若扩容不及、活跃请求打满 100% 上限API 会向客户端返回429 Too Many Requests。硬限能保证被接受的请求获得稳定性能代价是扩容不及时时可能拒绝部分请求。软限模式配置scaling.auto.engine.metrics.{speechToText,textToSpeech}.{batch,streaming}.requestsPerPod按每 Pod 目标请求数伸缩不会返回 429 拒绝请求若请求增速快于扩容速度个别请求性能可能劣化。values.yaml 中 Engine 自动伸缩的配套参数还包括minReplicas默认 1、maxReplicas默认 10、behaviorscaleDown 策略默认 Pods1/60s 与 Percent25/60s以及自定义指标custom。README 特别建议批式 STT、流式 STT、TTS 三类负载的时延与吞吐权衡差异较大应拆分独立环境部署。5.3 API 的按比例伸缩API 组件负责接收请求、组装响应并委派 Engine 推理。单个 API Pod 通常可以代理多个 Engine Pod因此按scaling.auto.api.metrics.engineToApiRatio默认 4即 Engine 与 API 的 Pod 数比值缩放 API 更省算力。5.4 底层指标管道自动伸缩依赖的 Prometheus 指标管道在 values.yaml 的kube-prometheus-stack与prometheus-adapter中预置Prometheus 通过dg_engine_metrics抓取任务2s 间隔采集 Engine 指标adapter 定义了engine_active_requests_stt_streaming、engine_active_requests_stt_batch、engine_active_requests_tts_batch、engine_estimated_stream_capacity、engine_requests_active_to_max_ratio、engine_to_api_pod_ratio等外部指标规则供 HPA 消费。若集群已有 Prometheus可将kube-prometheus-stack.includeDependency与prometheus-adapter.includeDependency置为false以复用既有监控栈。六、Voice Agent 内置支持与 LLM 提供方扩展v0.18.0 为 Chart 带来内置 Voice Agent 支持此后围绕它持续迭代v0.18.1 新增allowNonpublicEndpoints开关默认关闭用于自定义 LLM 端点指向localhost等非公网地址v0.22.0 将 Google 作为 Voice Agent Helm Chart 的第三方 LLM 提供方加入v0.23.1 修复了一个 TOML 解析器缺陷——Voice Agent 的 LLM 模型名若包含句点period会破坏 TOML 解析修复方式是对模型名加引号。当前 values.yaml 中agent配置块的结构为agent: enabled: false # 默认关闭 eotTimeoutMs: 3500 # 轮转结束检测超时毫秒 maxConversationChars: 15000 # 会话历史最大字符数 allowNonpublicEndpoints: false # 是否允许自定义端点使用非公网 URL llmProviders: # LLM 提供方及其可用模型 open_ai: # OpenAIgpt-4o-mini / gpt-3-5-turbo / gpt-4o anthropic: # AnthropicClaude 3 Haiku / Opus / 3.5 系列 groq: # GroqMixtral 8x7B / Llama 3 8B / 70B deepgram: # DeepgramLlama 3.1 8B Instruct x_ai: # xAIGrok 2 Latest google: # GoogleGemini 2.5/2.0 Flash 系列每个模型条目包含name展示名、tierstandard或advanced、public是否公开可见三个字段。当 Voice Agent 启用时scaling.replicas.engine支持按引擎类型分别指定副本数以适配不同语音引擎的独立伸缩需求。七、模型管理从 links 到 add/remove 的迁移与三种存储后端模型下载与持久化是 Engine 正确加载推理模型的前提CHANGELOG 记录了几次关键演变v0.6.0AWS 上的自动模型管理新增模型移除支持engine.modelManager.models.remove自动下载从links迁移到models.add旧字段仍兼容但官方建议迁移v0.8.0将 Engine Deployment 的 tolerations 同步应用到模型下载 Job确保下载任务能调度到与 Engine 相同的节点v0.5.0修正 03-basic-setup-onprem.yaml 中一条误导性注释——engine.modelManager.volumes.customVolumeClaim.name应指向PersistentVolumeClaim而非PersistentVolumev0.6.0修复了创建 Quay 凭据 Secret 的命令问题——此前用--from-file读取 Docker 配置文件某些本地密钥管理器如 Apple Keychain会清洗该文件导致 Secret 为空。当前 values.yaml 支持三种模型存储后端engine: modelManager: volumes: customVolumeClaim: # 自建 PV/PVC需 readWriteMany 或 readOnlyMany enabled: false name: # 预配置的 PVC 名称 modelsDirectory: / aws: efs: # AWS EFS需 EKS 环境 enabled: false namePrefix: dg-models fileSystemId: # 可用 aws efs describe-file-systems 查询 forceDownload: false gcp: gpd: # GCP 持久化磁盘需 GKE 环境 enabled: false namePrefix: dg-models storageClassName: standard-rwo storageCapacity: 40G volumeHandle: # projects/{project_id}/zones/{zone_name}/disks/{disk_name} fsType: ext4 models: links: [] # 已弃用建议迁移到 add add: [] # 自动下载的模型链接当前仅支持 AWS EFS remove: [] # 待移除的模型可填写完整链接或模型名值得注意的是自动模型管理目前仅对 AWS EFS 卷生效GCP GPD 与自定义 PVC 需要自行准备模型文件。八、License Proxy生产环境高可用的关键组件License Proxy 是可选但生产环境高度推荐的组件用于代理集群内所有许可请求。相关配置集中在 values.yaml 的licenseProxy块licenseProxy: enabled: false deploySecondReplica: false # 高可用环境可部署第二个副本 keepUpstreamServerAsBackup: true # 保留 upstream license 服务器作为回退 server: host: 0.0.0.0 port: 8443 # 许可验证请求监听端口 statusPort: 8080 # 状态/健康端点端口几个演进要点v0.2.0-beta 起 License Proxy 不再手动扩缩改为通过licenseProxy.{enabled,deploySecondReplica}间接控制keepUpstreamServerAsBackup允许 API/Engine Pod 在 Proxy 不可用时回退到上游license.deepgram.com若出于安全考虑限制 Pod 出站流量可将此开关关闭仅允许 Proxy 与上游通信其updateStrategy只暴露maxSurge而不暴露maxUnavailable目的是避免升级期间所有 License Proxy 同时下线导致整个集群与许可服务器断连。九、安全加固、调度策略与命名规范演进9.1 安全上下文与凭据v0.18.0 修复了 API/Engine Deployment 中securityContext模板引用与文档注释v0.20.0 将容器级container-levelsecurity context 支持加入 Helm 模板对应 values 中的api.containerSecurityContext、engine.containerSecurityContext、licenseProxy.containerSecurityContextv0.2.3 起imagePullSecrets变为可选0.6.0 修复了 Quay 凭据 Secret 创建命令的缺陷。凭据通过两个 Kubernetes Secret 引用注入values.yaml 顶部的global.pullSecretRef镜像仓库拉取凭据与global.deepgramSecretRef自托管 API Key。README 提示可按最小权限原则为 API、Engine、License Proxy 分别绑定自定义 ServiceAccount{api|engine|licenseProxy}.serviceAccount.createfalse 指定name。9.2 调度与拓扑v0.2.0-betaAWS 示例中 Deepgram 专用节点的标签从deepgram/nodeType更名为k8s.deepgram.com/node-type值不再带deepgram前缀v0.20.0为所有组件API、Engine、License Proxy新增nodeSelector支持v0.22.0新增topologySpreadConstraints可将同一 Deployment 的 Pod 均匀分布到不同可用区等拓扑域当前三个组件均支持v0.2.3修复 PVC 与 StorageClass 前缀命名不一致、以及自定义 ServiceAccount 名称报错的问题v0.2.1-betaConfigMap 变更时自动重启 Deepgram 容器保证配置热生效注解体系v0.3.0 支持 Deployment 自定义注解v0.15.0 将注解应用到 Deployment 资源的 template 段v0.23.0 修复 API 模板中additionalLabels的引用错误。9.3 优雅关停与滚动更新global.outstandingRequestGracePeriod默认 1800 秒定义了容器收到 SIGTERM 后等待存量批式/流式请求完成的宽限期——批式请求通常在 10~15 分钟内完成流式请求可能无限持续超过宽限期 Kubernetes 将强制终止。API/Engine 的滚动更新默认maxUnavailable: 0、maxSurge: 1即滚动期间不允许已有 Pod 下线先创建超额 Pod 再切换保障在线服务的可用性。9.4 自定义 TOML 扩展v0.20.0 开放了api.customToml与engine.customToml允许在 Chart 生成的api.toml、engine.toml之外追加自定义 TOML 段对应模板见 templates/api/api.config.yaml 与 templates/engine/engine.config.yaml为高级调优提供逃生通道。十、健康检查、状态端点与可观测性v0.24.0 将/v1/status端点扩展为四种状态Initializing初始化中、Ready就绪、Healthy健康、Critical严重为自动化监控与告警提供更细粒度语义Engine 提供独立指标端点engine.metricsServer默认0.0.0.0:9991输出推理相关系统指标探针体系values.yaml 中api.*Probe、engine.*ProbeEngine 的startupProbe默认periodSeconds: 10、failureThreshold: 60为模型加载预留最长约 10 分钟时间窗口——若模型常驻网络卷加载耗时受 I/O 与网络影响可在命中失败阈值前调大探针readinessProbe默认initialDelaySeconds: 5, periodSeconds: 10, failureThreshold: 1livenessProbe默认failureThreshold: 3监控栈由内置kube-prometheus-stackPrometheus Grafana kube-state-metrics提供README 排障章节建议依次检查kubectl get pods、kubectl logs pod-name、kubectl get events并用helm get values [RELEASE_NAME] my-deployed-values.yaml导出已部署配置用于诊断。十一、从 alpha 到 GA 的关键里程碑时间线版本时间里程碑意义0.1.0-alpha2024-05-31Chart 初始实现0.2.0-beta2024-06-20引入 cluster-autoscaler 与 Pod 自动伸缩、License Proxy 备份、副本数配置迁移0.2.32024-07-15新增 on-prem 示例 values、imagePullSecrets 可选、自定义 ServiceAccount0.4.02024-07-25实体检测功能开关默认关闭、多语言码切换模型0.5.02024-08-27预录音频英语实体检测/脱敏 GA、onprem更名self-hosted0.6.02024-09-27运行期模型自动加载NFS/CSI 免重启、模型管理 add/remove0.7.02024-10-24streaming WebSocket TTS、EKS accelerated AMI0.11.12025-03-28开放 NER 模型配置0.18.02025-08-28内置 Voice Agent、securityContext 修复0.19.02025-09-12NER 格式化默认开启Nova-3 必需0.20.02025-09-17Service 类型可配置、默认改 ClusterIP、nodeSelector、customToml0.22.02025-10-15Google LLM 提供方、topologySpreadConstraints、entity_redaction 默认开启0.23.02025-10-29示例集群配置升级至 Kubernetes 1.330.24.02025-11-1836 语言检测开关、/v1/status 四态化十二、结论与实践建议纵观 CHANGELOG这个 Chart 的演进遵循三条清晰主线默认更安全ClusterIP 化、redactUsage 与 entity_redaction 默认开启、容器级 securityContext、默认更弹性HPA 与节点伸缩成熟、软硬限双模式、拓扑分布、能力跟随模型迭代Nova-3 NER 格式化、36 语言检测、Voice Agent 多 LLM 提供方。在友邻项目Friend/omi中该 Chart 已通过 dev_omi_values.yaml 与 prod_omi_values.yaml 落地为实际部署 overlay说明其具备真实的开发与生产双环境支撑能力。对于准备在生产环境使用该 Chart 的团队建议按以下清单落地版本基线保持 Kubernetes 1.28安装前确认 Helm 版本 3.7并核对appVersion对应的容器镜像标签密钥先行按 README.md 提前创建pullSecretRef镜像仓库凭据与deepgramSecretRefAPI Key两个 SecretNova-3 必备保持formatEntityTags、streamingNer、entityRedaction默认开启如需 36 语言检测再开启useV2LanguageDetection网络与安全按负载类型选择 Service 类型LoadBalancer 场景务必配置loadBalancerSourceRanges与externalTrafficPolicy伸缩设计区分批式/流式 STT 与 TTS 的伸缩指标先小规模验证requestCapacityRatio与requestsPerPod的取值再全量上线模型存储优先 AWS EFS 以获得自动模型管理能力其他存储需提前准备模型文件并正确设置 PVC 访问模式。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考