Athithya-Sakthivel/fastembed-inference-helm

# FastEmbed 推理 Helm Chart ## 概述 此 Helm Chart 打包了三个独立但相关的推理服务： | 服务 | 描述 | 默认模型 | 默认端口 | | -------- | ---------------------------------------- | --------------------------------------- | -------- | | **Dense** | 从文本生成稠密向量嵌入。 | `BAAI/bge-small-en-v1.5` | `8200` | | **Sparse** | 为文本生成稀疏向量嵌入。 | `Qdrant/minicoil-v1` | `8201` | | **Reranker** | 根据查询对文档列表重新排序。 | `Xenova/ms-marco-MiniLM-L-6-v2` | `8202` | 每个服务都作为一个独立的 Kubernetes Deployment 部署，通过 ClusterIP Service 暴露，并且可以独立扩展、配置以及启用或禁用。 ## 架构 ``` ┌─────────────────────────────────────┐ │ Kubernetes Cluster │ │ │ ┌──────────┐ │ ┌───────────┐ ┌──────────────┐ │ │ Client/ │────▶│ │ Dense │ │ Reranker │ │ │ RAG App │ │ │ Service │ │ Service │ │ └──────────┘ │ │ (8200) │ │ (8202) │ │ │ └───────────┘ └──────────────┘ │ │ ┌───────────┐ │ │ │ Sparse │ │ │ │ Service │ │ │ │ (8201) │ │ │ └───────────┘ │ │ │ │ ┌──────────────────────────────┐ │ │ │ Prometheus Metrics Endpoint │ │ │ │ (/metrics on each service) │ │ │ └──────────────────────────────┘ │ └─────────────────────────────────────┘ ``` ## 前置条件 - Kubernetes 1.21+ - Helm 3.8+ - （可选）如果启用了网络策略，则需要一个支持 `NetworkPolicy` 的 CNI 插件（例如 Calico、Cilium）。 - （可选）如果要进行 GPU 加速，则需要 NVIDIA GPU operator 和具有 `nvidia.com/gpu` 资源的节点。 - （可选）如果使用 `monitoring.mode: servicemonitor`，则需要 Prometheus Operator。 ## 快速开始（幂等） 可选地导出 HF_TOKEN 并添加 Helm 仓库，然后使用默认值安装 Chart： ``` export HF_TOKEN="your_huggingface_token_here" # 添加 Helm 存储库 helm repo add fastembed https://athithya-sakthivel.github.io/fastembed-inference-helm 2>/dev/null || true helm repo update # 如果命名空间不存在则创建命名空间 kubectl create namespace fastembed --dry-run=client -o yaml | kubectl apply -f - # 设置 Hugging Face 令牌 kubectl create secret generic hf-token \ --namespace fastembed \ --from-literal=HF_TOKEN=$HF_TOKEN \ --dry-run=client -o yaml | kubectl apply -f - # 安装或升级 release helm upgrade --install fastembed fastembed/fastembed-inference \ --namespace fastembed \ --set global.huggingface.existingSecret=hf-token \ --set dense.preloadModel=true \ --set sparse.preloadModel=true \ --set reranker.preloadModel=true \ --wait \ --timeout 10m ``` 这将使用合理的默认值以纯 CPU 模式部署所有三项服务。 ## 配置 此 Chart 通过单个 `values.yaml` 文件进行配置。主要的配置部分如下： ### 全局设置 | 参数 | 描述 | 默认值 | | ----------------------------------- | ----------------------------------------------------------- | ------ | | `global.createNamespace` | 如果发布命名空间不存在，则创建它。 | `true` | | `global.cuda` | GPU 支持的主开关。需要兼容 GPU 的镜像。 | `false` | | `global.monitoring.enabled` | 在所有服务上暴露 Prometheus `/metrics` 端点的主开关。 | `true` | | `global.monitoring.mode` | 抓取模式：`static`（手动 Prometheus 配置）或 `servicemonitor`（CRD）。 | `static` | | `global.networkPolicy.enabled` | 强制执行基于命名空间的网络隔离。 | `true` | | `global.networkPolicy.allowedNamespaces` | 允许调用这些服务的命名空间列表。 | `[inference, indexing, monitoring, kube-prometheus-stack]` | | `global.huggingface.existingSecret` | 包含用于门控模型的 `HF_TOKEN` 的 Kubernetes Secret 的名称。 | `""` | ### 特定服务设置 每个服务（`dense`、`sparse`、`reranker`）都可以使用以下通用参数进行配置： | 参数 | 描述 | Dense 默认值 | Sparse 默认值 | Reranker 默认值 | | ------------------- | ------------------------------------------------------------ | --------------------------- | ------------------------- | ------------------------------ | | `enabled` | 启用或禁用服务部署。 | `true` | `true` | `true` | | `modelName` | 来自 Hugging Face Hub 或本地路径的模型 ID。 | `BAAI/bge-small-en-v1.5` | `Qdrant/minicoil-v1` | `Xenova/ms-marco-MiniLM-L-6-v2` | | `batchSize` | 每个请求的最大文本/文档数量。 | `16` | `16` | `16` | | `gpuCount` | 请求的 `nvidia.com/gpu` 资源数量（仅当 `global.cuda: true` 时）。 | `1` | `0` | `1` | | `port` | 容器 HTTP 端口。 | `8200` | `8201` | `8202` | | `preloadModel` | 在启动时加载 ML 模型，而不是在首次请求时延迟加载。 | `false` | `false` | `true` | | `replicas` | 当 HPA 禁用时运行的 Pod 数量。 | `1` | `1` | `1` | | `hpa.enabled` | 启用基于 CPU 的水平 Pod 自动扩缩容。 | `false` | `false` | `false` | | `hpa.min`/`hpa.max` | HPA 的最小/最大副本数。 | `1` / `3` | `1` / `3` | `1` / `3` | | `hpa.targetCPU` | HPA 的目标平均 CPU 利用率。 | `60` | `60` | `60` | | `pdb.enabled` | 当 `replicas > 1` 时创建 PodDisruptionBudget。 | `true` | `true` | `true` | 要查看所有可调参数的完整列表，请参阅 [`values.yaml`](./chart/values.yaml) 文件。 ## 监控与可观测性 每个服务在 `/metrics` 端点上暴露了一组丰富的 Prometheus 指标，包括： - `dense|sparse|reranker_requests_total` - 按状态统计的总请求数。 - `dense|sparse|reranker_request_duration_seconds` - 请求延迟直方图。 - `dense|sparse|reranker_requests_in_progress` - 进行中请求的计量值。 - `dense|sparse|reranker_errors_total` - 按类型统计的错误计数。 当 `global.monitoring.mode: servicemonitor` 时，会自动创建一个 Prometheus Operator `ServiceMonitor` 来抓取所有服务。对于 `static` 模式，您必须手动配置您的 Prometheus 实例来抓取服务端点。有关示例，请参阅[监控文档](./docs/infra/monitoring.md)。 ## 网络安全 当 `global.networkPolicy.enabled: true` 时，此 Chart 使用 Kubernetes `NetworkPolicy` 资源强制执行零信任网络模型。 - **默认拒绝所有**：默认拒绝所有到 Pod 的入站流量。 - **显式允许的入站**：只有 `allowedNamespaces` 中列出的命名空间中的 Pod 才能访问这些服务。 - **到 DNS 的出站**：始终允许。 - **到互联网的出站**：由 `global.networkPolicy.allowInternetEgress` 控制。如果模型未预缓存，首次使用时 Hugging Face 模型下载需要此设置。 有关详细解释，请参阅[网络策略文档](./docs/infra/networkpolicy.md)。 ## API 端点 所有服务共享一组通用的管理端点。 ### Dense 服务 (`:8200`) - `POST /embed` - 为文本列表生成稠密嵌入。 - `GET /health` - 存活检查。返回服务状态和配置。 - `GET /readyz` - 就绪探针。当模型已加载并准备好时返回 `200 OK`。 - `GET /metrics` - Prometheus 指标端点。 有关使用示例和支持的模型，请参阅完整的 [dense 服务文档](./docs/images/dense.md)。 ### Sparse 服务 (`:8201`) - `POST /embed` - 为文本列表生成稀疏嵌入（索引和值）。 - `GET /health` - 存活检查。 - `GET /readyz` - 就绪探针。 - `GET /metrics` - Prometheus 指标端点。 有关使用示例和支持的模型，请参阅完整的 [sparse 服务文档](./docs/images/sparse.md)。 ### Reranker 服务 (`:8202`) - `POST /rerank` - 根据查询字符串对文档列表重新排序。返回相关性分数列表。 - `GET /health` - 存活检查。 - `GET /readyz` - 就绪探针。 - `GET /metrics` - Prometheus 指标端点。 有关使用示例和支持的模型，请参阅完整的 [reranker 服务文档](./docs/images/reranker.md)。 ## 使用示例 ``` # 终止现有 port-forwards 并启动所有 3 个 pkill -f "port-forward.*fastembed" 2>/dev/null || true sleep 1 kubectl port-forward -n fastembed svc/fastembed-dense-svc 8200:8200 &>/dev/null & kubectl port-forward -n fastembed svc/fastembed-sparse-svc 8201:8201 &>/dev/null & kubectl port-forward -n fastembed svc/fastembed-reranker-svc 8202:8202 &>/dev/null & sleep 2 # 简洁测试所有 endpoints 和 metric 值 echo "=== DENSE ===" && curl -sf http://localhost:8200/health && curl -sf http://localhost:8200/readyz && curl -sf -X POST http://localhost:8200/embed -H "Content-Type: application/json" -d '{"texts":["test"]}' && echo "" && curl -sf http://localhost:8200/metrics | grep "dense_requests_total{" echo "=== SPARSE ===" && curl -sf http://localhost:8201/health && curl -sf http://localhost:8201/readyz && curl -sf -X POST http://localhost:8201/embed -H "Content-Type: application/json" -d '{"texts":["test"]}' && echo "" && curl -sf http://localhost:8201/metrics | grep "sparse_requests_total{" echo "=== RERANKER ===" && curl -sf http://localhost:8202/health && curl -sf http://localhost:8202/readyz && curl -sf -X POST http://localhost:8202/rerank -H "Content-Type: application/json" -d '{"query":"test","documents":["a","b"]}' && echo "" && curl -sf http://localhost:8202/metrics | grep "reranker_requests_total{" echo "All services running on localhost:8200-8202" echo "Stop: pkill -f 'port-forward.*fastembed'" ``` ## 文档 - **服务文档**: - [Dense 嵌入服务](docs/images/dense.md) - [Sparse 嵌入服务](docs/images/sparse.md) - [Reranker 服务](docs/images/reranker.md) - **基础设施文档**: - [CUDA / GPU 支持](docs/infra/cuda.md) - [监控与指标](docs/infra/monitoring.md) - [网络策略安全模型](docs/infra/networkpolicy.md)

标签：Apex, GPU支持, Helm chart, RAG, REST API, 人工智能, 向量搜索, 子域名突变, 容器部署, 文本处理, 文本嵌入, 无状态, 机器学习, 用户模式Hook绕过, 网络测绘, 自定义请求头, 语义嵌入, 语义搜索, 重排序