使用 Hindsight Helm Chart 在 Kubernetes 上部署 Agent 记忆系统【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文是一份完整的 Hindsight Helm Chart 部署指南。Hindsight 是一套面向 AI Agent 的时序-语义-实体记忆系统temporal-semantic-entity memory system本 Chart 用于将其以标准 Kubernetes 工作负载的形式交付涵盖 API 服务、Control Plane 控制台、可选 Worker 任务节点、PostgreSQL 数据库与可选的 TEI 推理服务。读完本文你将掌握从零初始化 Helm 依赖、以内置或外部 PostgreSQL 完成安装、按需配置 Worker 与 TEI、接入 Ingress 与 Prometheus 监控以及完成升级卸载的完整操作链路。前置条件在开始之前请确保环境满足以下要求Kubernetes 1.19Chart 中使用了apps/v1、networking.k8s.io/v1、autoscaling/v2、monitoring.coreos.com/v1等 API 版本均要求该 Kubernetes 版本及以上Helm 3.0Chart 采用 Helm v2 Chart 规范见 Chart.yamlapiVersion: v2仅支持 Helm 3PostgreSQL 数据库可以随 Chart 一起部署内置实例默认使用带 pgvector 扩展的镜像也可以接入外部已有数据库。Chart 的当前版本为0.9.2对应appVersion: 0.9.2即默认镜像 tag。快速开始更新依赖Chart 本身不依赖外部子 ChartPostgreSQL 以内置 StatefulSet 形式渲染而非 subchart但官方流程仍建议先更新依赖确保本地 Chart 与远端一致helm dependency update ./helm/hindsight安装内置 PostgreSQL默认开启默认配置会随 Chart 一起部署 PostgreSQL使用ankane/pgvector镜像因此只需注入 LLM API Key 即可完成最小化安装# Install (PostgreSQL included by default) export OPENAI_API_KEYsk-your-openai-key helm upgrade hindsight --install ./helm/hindsight -n hindsight --create-namespace \ --set api.secrets.HINDSIGHT_API_LLM_API_KEY$OPENAI_API_KEY这里使用helm upgrade --install的幂等写法命名空间不存在时通过--create-namespace自动创建后续重复执行同一命令即可实现升级。使用外部数据库如果希望复用已有 PostgreSQL 实例只需关闭内置数据库并填写外部连接信息helm install hindsight ./helm/hindsight -n hindsight --create-namespace \ --set api.secrets.HINDSIGHT_API_LLM_API_KEYsk-your-openai-key \ --set postgresql.enabledfalse \ --set postgresql.external.hostmy-postgres.example.com \ --set postgresql.external.passwordmypassword外部数据库的连接串由_helpers.tpl中的hindsight.databaseUrl模板动态生成postgresql://username:$(POSTGRES_PASSWORD)host:port/database其中密码通过$(POSTGRES_PASSWORD)占位并在 Deployment 中以secretKeyRef方式注入避免密码明文出现在连接串中。安装方式详解添加仓库若已发布如果 Chart 已发布到远端 Helm 仓库可以按标准流程添加并同步helm repo add hindsight https://your-helm-repo.com helm repo update注意该仓库地址为占位示例当前仓库内 Chart 以源码形式存放在helm/hindsight/未发布到公开仓库时直接使用本地路径即可。使用自定义 values 文件安装推荐的做法是编写values-override.yaml将环境相关配置与命令分离api: secrets: HINDSIGHT_API_LLM_API_KEY: sk-your-openai-key postgresql: external: host: my-postgres.example.com password: mypassword然后执行helm install hindsight ./helm/hindsight -n hindsight --create-namespace -f values-override.yaml核心配置参数Key Values 总览ParameterDescriptionDefaultversion所有组件的默认镜像 tagChartappVersionapi.enabled是否启用 API 组件trueapi.image.repositoryAPI 镜像仓库ghcr.io/vectorize-io/hindsight-apiapi.image.tagAPI 镜像 tag默认取version-api.service.portAPI 服务端口8888controlPlane.enabled是否启用 Control PlanetruecontrolPlane.image.repositoryControl Plane 镜像仓库ghcr.io/vectorize-io/hindsight-control-planecontrolPlane.image.tagControl Plane 镜像 tag默认取version-controlPlane.service.portControl Plane 服务端口3000postgresql.enabled是否以内置方式部署 PostgreSQLtruepostgresql.external.host外部 PostgreSQL 主机postgresqlpostgresql.external.port外部 PostgreSQL 端口5432postgresql.external.database数据库名hindsightpostgresql.external.username数据库用户名hindsightingress.enabled是否启用 Ingressfalseautoscaling.enabled是否启用 HPAfalsemetrics.serviceMonitor.enabled是否为 api/worker 创建 ServiceMonitor需 Prometheus Operatorfalsemetrics.serviceMonitor.labels供 Prometheus Operator 选择的标签如release: kube-prometheus-stack{}镜像 tag 的解析规则见各工作负载模板例如 api-deployment.yaml 中的image: {{ .Values.api.image.repository }}:{{ .Values.api.image.tag | default .Values.version | default .Chart.AppVersion }}优先级为image.tag→ 全局version→ ChartappVersion。因此发布新版本时只需更新Chart.yaml的appVersion或统一设置version即可让所有组件同步切换镜像。环境变量与密钥api.env、worker.env、controlPlane.env中的键值会被逐条渲染进对应 Pod 的环境变量敏感信息则应放在api.secrets或controlPlane.secrets中——它们由 secret.yaml 统一生成 Kubernetes Secret值经b64enc编码再通过secretKeyRef注入避免出现在 Pod 定义或 values 明文环境变量中。api: env: HINDSIGHT_API_LLM_PROVIDER: openai HINDSIGHT_API_LLM_MODEL: gpt-4 secrets: HINDSIGHT_API_LLM_API_KEY: your-api-key HINDSIGHT_API_LLM_BASE_URL: https://api.openai.com/v1 controlPlane: env: NODE_ENV: production secrets: {}从源码看这些 LLM 环境变量正是 Hindsight API 读取的核心配置项。config.py 中定义了HINDSIGHT_API_LLM_PROVIDER、HINDSIGHT_API_LLM_API_KEY、HINDSIGHT_API_LLM_MODEL三个环境变量常量分别映射到 LLM 提供方、API Key 与模型名。也就是说通过api.env/api.secrets注入的配置会直接决定 API 使用哪家模型服务。当前 values.yaml 中默认模型为openai/gpt-oss-120b使用 LiteLLM 风格的 provider/model 命名注释中还给出了 Groq 的示例HINDSIGHT_API_LLM_PROVIDER: groq配合HINDSIGHT_API_LLM_BASE_URL: https://api.groq.com/openai/v1说明该系统支持通过 provider 路由到不同 LLM 后端。使用现有 SecretexistingSecret除 Chart 自动生成的 Secret 外还可以预先创建 Secret 并通过existingSecret引用。启用后该 Secret 的所有键会通过envFrom整体注入 Pod见 api-deployment.yaml 与 worker-statefulset.yaml此时api.secrets/controlPlane.secrets不再参与渲染Secret 内容的变更也不会触发checksum/secret注解导致的滚动更新# values.yaml 顶层 existingSecret: my-hindsight-secret使用外部数据库时该 Secret 必须包含postgres-password键供POSTGRES_PASSWORD引用其余任意键都会成为注入的环境变量例如HINDSIGHT_API_LLM_API_KEY。Worker 环境变量的合并规则Worker 与 API 共用镜像ghcr.io/vectorize-io/hindsight-api其环境变量采用合并继承策略见 worker-statefulset.yaml 中的merge模板调用默认继承api.env与api.secretsworker.env/worker.secrets中的同名键优先覆盖。这样既保证 Worker 与 API 的 LLM 配置一致又允许对任务处理行为单独调参。外部数据库连接postgresql.enabledfalse时以下配置生效postgresql: enabled: false external: host: my-postgres.example.com port: 5432 database: hindsight username: hindsight password: your-password外部密码会写入 Secret 的postgres-password键Deployment 中先注入POSTGRES_PASSWORD再渲染带$(POSTGRES_PASSWORD)占位符的HINDSIGHT_API_DATABASE_URL利用 Kubernetes 的$(VAR)环境变量插值机制完成连接串拼装模板中明确注释了POSTGRES_PASSWORD必须先于DATABASE_URL定义。内置 PostgreSQL 参数内置部署使用ankane/pgvector镜像自带向量扩展契合 Hindsight 的语义向量检索需求单副本 StatefulSet 8Gi 持久卷探针基于pg_isreadypostgresql: image: repository: ankane/pgvector tag: latest auth: username: hindsight password: hindsight database: hindsight service: port: 5432 persistence: enabled: true size: 8Gi对应模板 postgresql-statefulset.yaml 使用volumeClaimTemplates声明持久卷若将persistence.enabled设为false数据卷会退化为emptyDirPod 重建即丢失仅适合测试。Sidecar 与 Init Containerapi、worker、controlPlane三组组件均支持extraContainers与extraInitContainers默认均为[]为空时不渲染任何内容。典型场景是需要与主容器共享 Pod 网络的本地代理容器——例如通过 localhost 访问的数据库鉴权代理api: extraContainers: - name: cloud-sql-proxy image: gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.24.1 args: - --port5432 - my-project:us-west1:my-instance securityContext: runAsNonRoot: true postgresql: enabled: false external: host: 127.0.0.1主容器通过127.0.0.1:5432访问代理代理再转发到云托管的数据库。同理init 容器可用来实现等待数据库就绪之类的前置逻辑如until nc -z postgresql 5432。此外api还支持extraVolumes/extraVolumeMounts可将 ConfigMap 或自定义卷挂载进 API Pod。Ingress默认ingress.enabledfalse。开启后可将 Control Plane前端控制台与 API 暴露到集群外典型的 nginx ingress cert-manager 自动证书配置如下ingress: enabled: true className: nginx annotations: cert-manager.io/cluster-issuer: letsencrypt-prod hosts: - host: hindsight.example.com paths: - path: / pathType: Prefix service: controlPlane - path: /api pathType: Prefix service: api tls: - secretName: hindsight-tls hosts: - hindsight.example.comingress.yaml 会根据paths[].service字段的值api或controlPlane自动解析到对应的 Servicerelease-api端口取api.service.port默认 8888或release-control-plane端口取controlPlane.service.port默认 3000。因此前端页面走根路径/API 走/api前缀。Prometheus 指标采集API端口 8888与 Worker端口 8889容器会在/metrics暴露 Prometheus 格式指标Control PlaneNext.js不暴露指标。在装有 Prometheus Operator 的集群如 kube-prometheus-stack上可以开启 ServiceMonitor 自动发现metrics: serviceMonitor: enabled: true labels: release: kube-prometheus-stack # 必须与 stack 的 serviceMonitorSelector 匹配servicemonitor.yaml 会为api与worker分别创建 ServiceMonitor二者共用path: /metrics、interval: 30s、scrapeTimeout: 10s等端点参数。Worker 的 ServiceMonitor 仅在worker.enabled: true时生成。若集群没有 Prometheus Operator可以直接以注解发现或静态目标方式抓取svc/release-api:8888/metrics与svc/release-worker:8889/metrics。可选组件Worker 与 TEI分布式 WorkerStatefulSetworker.enabledfalse时任务由 API 内部的 worker 处理。开启后Chart 会部署独立的 Worker StatefulSet默认 2 副本并在 API 中自动注入HINDSIGHT_API_WORKER_ENABLEDfalse关闭其内部 worker见 api-deployment.yaml实现任务处理的横向扩展。Worker 使用command: [hindsight-worker]启动其专属环境变量在 values.yaml 中均有注释说明环境变量默认值含义HINDSIGHT_API_WORKER_POLL_INTERVAL_MS500任务轮询间隔毫秒HINDSIGHT_API_WORKER_BATCH_SIZE10每轮轮询认领的任务数HINDSIGHT_API_WORKER_MAX_RETRIES3任务失败前的最大重试次数HINDSIGHT_API_WORKER_HTTP_PORT8889指标/健康检查 HTTP 端口与 service.targetPort 一致由于 Worker 是 StatefulSetHINDSIGHT_API_WORKER_ID通过fieldRef: metadata.name取自 Pod 名worker-0、worker-1…保证每个副本有稳定唯一的 Worker ID其模型缓存则通过volumeClaimTemplates为每个副本分配独立 PVC。Worker 的健康探针同样区分存活与就绪存活探针走/health/live不访问数据库避免数据库慢时因重启导致已认领任务带retry_count重新入队。健康探针设计要点三个组件的探针设计见 values.yaml 注释遵循同一个原则存活探针liveness使用/health/liveAPI/Worker或 TCP 端口检查Control Plane不访问数据库。数据库慢或不可达时只应把 Pod 摘出 Service就绪探针的职责而不是重启 Pod——重启 Worker 会使其已认领的任务带着递增的retry_count重新入队就绪探针readiness使用/healthAPI/Worker会检查数据库或 TCP 检查Control Plane数据库恢复后 Pod 自动回到 Service 轮询池探针依赖appVersion及更新版本的镜像旧镜像只有/health会因 404 导致探针失败。TEIText Embeddings InferenceChart 内置了 Hugging Face TEI 的可选部署用于本地托管重排序reranker与嵌入embedding模型避免将模型请求发送到外部服务tei: reranker: enabled: false model: cross-encoder/ms-marco-MiniLM-L-6-v2 port: 8090 embedding: enabled: false model: sentence-transformers/all-MiniLM-L6-v2 port: 8091启用后API 会自动注入HINDSIGHT_API_RERANKER_PROVIDERtei与HINDSIGHT_API_RERANKER_TEI_URLhttp://release-tei-reranker:8090以及对应的HINDSIGHT_API_EMBEDDINGS_PROVIDER/HINDSIGHT_API_EMBEDDINGS_TEI_URL见 api-deployment.yaml默认资源为 2CPU/2Gi探针通过/health检查failureThreshold: 6模型加载较慢时避免误杀。本地模型缓存API 与 Worker 首次使用本地模型reranker、embedding时模型会下载到/home/hindsight/.cache。persistence.modelCache.enabledtrue可将该目录持久化避免每次 Pod 重启都重新下载。但 values 注释给出了明确的工程建议生产环境优先将模型烘焙进自定义镜像而不是启用 PVC——镜像层每个节点只拉取一次且天然缓存而 PVC 会带来存储成本、ReadWriteOnce导致 Pod 被钉在单节点以及卸载/升级时的生命周期管理负担。模型缓存 PVC 模板见 api-model-cache-pvc.yamlAPI 为单 PVCWorker 为每副本 PVC。弹性伸缩与其他运维配置水平自动伸缩HPAautoscaling.enabledtrue时hpa.yaml 会为 API 与 Control Plane 两个 Deployment 分别创建autoscaling/v2的 HorizontalPodAutoscalerautoscaling: enabled: false minReplicas: 1 maxReplicas: 10 targetCPUUtilizationPercentage: 80 targetMemoryUtilizationPercentage: 80CPU 与内存利用率阈值可分别配置设置为 0 或省略则不对应指标不参与伸缩。开启 HPA 后两个 Deployment 的replicas字段不再由 values 中的replicaCount渲染避免与 HPA 竞争副本数。安全上下文与调度Chart 默认注入较强的 Pod 安全配置见 values.yamlPod 安全上下文fsGroup: 1000容器安全上下文runAsNonRoot: true、runAsUser: 1000、drop: [ALL]、allowPrivilegeEscalation: falsereadOnlyRootFilesystem: false因模型缓存需要写文件系统顶层支持nodeSelector、tolerations、affinity其中 affinity 为全局默认各组件可通过api.affinity/worker.affinity/controlPlane.affinity单独覆盖serviceAccount.createtrue时自动创建 ServiceAccountpodAnnotations可注入任意 Pod 注解。Pod 干扰预算PDB三个组件均支持podDisruptionBudget默认关闭开启后以minAvailable: 1保护至少一个副本可用避免节点维护时服务中断。升级与卸载升级沿用快速安装的幂等命令helm upgrade hindsight ./helm/hindsight -n hindsight卸载helm uninstall hindsight -n hindsight注意helm uninstall默认会删除 Chart 创建的 Secret、Service、StatefulSet 等资源但不会自动删除 PVCPostgreSQL 数据卷、模型缓存卷。若需彻底清理数据需要在卸载后手动处理对应 PVC。Chart 部署的组件一览组件工作负载类型镜像端口职责APIDeploymentghcr.io/vectorize-io/hindsight-api8888Hindsight 记忆操作的主 API 服务Control PlaneDeploymentghcr.io/vectorize-io/hindsight-control-plane3000管理 Agent、查看记忆的 Web UIWorker可选StatefulSetghcr.io/vectorize-io/hindsight-api8889分布式任务处理PostgreSQL可选StatefulSetankane/pgvector5432内置数据库带向量扩展TEI reranker/embedding可选Deploymentghcr.io/huggingface/text-embeddings-inference8090/8091本地重排序与嵌入推理模板文件均位于 helm/hindsight/templates 目录包括api-deployment.yaml、controlplane-deployment.yaml、worker-statefulset.yaml、postgresql-statefulset.yaml、ingress.yaml、hpa.yaml、servicemonitor.yaml、secret.yaml、pdb.yaml、serviceaccount.yaml及各 Service 定义。Control Plane 通过模板hindsight.apiUrl生成HINDSIGHT_CP_DATAPLANE_API_URLhttp://release-api:8888注入 API 地址实现前后端联动。开发与调试Chart 提供三个标准的本地校验手段建议在改动 values 后依次执行# 1. 静态校验 Chart 结构与 values 合法性 helm lint ./helm/hindsight # 2. 本地渲染模板检查生成的 YAML--debug 可查看模板变量解析过程 helm template hindsight ./helm/hindsight --debug # 3. 模拟安装不实际创建资源仅校验能否通过 API Server 的校验 helm install hindsight ./helm/hindsight --dry-run --debug其中helm template是排查模板渲染问题的首选它完全离线执行能直接看到_helpers.tpl中hindsight.fullname、hindsight.databaseUrl、hindsight.apiUrl等辅助模板见 _helpers.tpl的实际输出结果。另外Secret 内容发生变更时Deployment 会通过checksum/secret注解sha256sum计算自动触发滚动更新使新密钥无需手动重启即可生效。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考