Kubeflow 文档 AI 助手

这个 Agent 能做什么，适合哪些场景？

这是 Kubeflow 文档助手的官方 LLM 实现，基于检索增强生成（RAG），让用户跨 Kubeflow 文档进行语义搜索并获得带上下文的回答。检索侧由 Milvus 承担，生产环境使用 RAG v4 混合检索：768 维 MPNet 稠密向量加原生 BM25 稀疏向量，并带类型化的 release_date 字段。生成侧由 KServe 上的 vLLM 后端提供 Llama 3.1-8B-Instruct（RedHatAI/Llama-3.1-8B-Instruct），开启自动工具调用与 llama3_json 解析器。数据接入由 Kubeflow Pipelines 完成，包括仓库抓取、规范化解析与分块、调用集群内 TEI 服务生成向量、最后写入 Milvus 的 v4 混合 schema。对外接口有两套：server/app.py 的 WebSocket API 和 server-https/app.py 的 FastAPI HTTPS API，均支持流式与非流式响应、工具调用和引用自动收集去重。仓库还包含 MCP 服务器、kagent 控制器、Terraform 平台栈与 gateway-guardrails Helm 图表，将整个系统部署在 Kubernetes（OKE）之上。

系统从 GitHub 仓库（默认 kubeflow/website 的 content/en 目录）抓取 .md 与 .html 文档，经 canonical_rag_ingest.py 做 Hugo/Markdown 规范化解析、按 token 分块并抽取 release_date，再通过集群内 TEI 服务生成 768 维向量，以 pymilvus 批量写入 Milvus 的稠密加原生 BM25 混合索引。查询阶段，docs-agent-mcp/mcp-server/server.py 以确定性意图路由（SEARCH_MODE=auto）在 Milvus 上做 v4 混合检索，把带引用的片段交给 KServe 的 llama3.1-8B 推理服务生成答案，模型只输出结构化引用而不渲染 URL。对外由 WebSocket 的 handle_websocket / stream_llm_response 或 HTTPS 的 POST /chat 提供流式（SSE 事件 content、tool_result、citations、done）与非流式 JSON（response、citations）两种响应，GET /health 供 Kubernetes 探针使用。基础设施由 docs-agent-mcp/terraform 下的 namespaces.tf、knative.tf、kubeflow_pipelines.tf、milvus.tf、kagent.tf、gateway_guardrails.tf 声明式编排，gateway-guardrails 图表提供 Istio 网关 TLS、CORS 锁定、每分钟 60 次限流和零信任 AuthorizationPolicy。CI 由 oke-cicd.yaml 与 tests.yml 完成流水线编译、ruff、pytest、镜像推送 GHCR 及可选 OKE 部署。

1. Kubeflow 平台运维人员收到用户提问“如何创建 pipeline”，希望获得带官方文档引用的准确回答。
2. 文档维护者在发布新版本文档后，希望重新跑 KFP 接入流水线更新 Milvus 集合而不重建整套服务。
3. 平台团队需要在自有 Kubernetes/OKE 上部署一个只在内部使用的文档问答服务，并通过 Terraform 复现。
4. 前端工程师要把问答组件嵌入 Kubeflow 官网，只需要 POST /chat 并消费 SSE 事件与 citations 字段。
5. Agent 开发者希望用 MCP 客户端复用同一套检索与引用逻辑，而不是自己实现切分与向量检索。
6. 安全团队要求对外暴露的聊天入口具备 TLS、CORS 白名单和速率限制，可直接使用 gateway-guardrails 图表的默认值。

如何安装或部署这个 Agent？

前置条件：Kubernetes 1.20+、Helm 3.x、Kubeflow Pipelines、用于 LLM 推理的 GPU 节点，以及受信任 CA 签发的 SSL 证书（浏览器会拦截无效证书下的 WebSocket 与 HTTPS 请求）。

先在 docs-agent 命名空间安装 Milvus（standalone 模式）：

helm repo add milvus https://milvus-io.github.io/milvus-helm/
helm repo update

helm upgrade --install my-release zilliztech/milvus -n docs-agent \
  --set cluster.enabled=false \
  --set standalone.enabled=true \
  --set etcd.replicaCount=1 \
  --set etcd.persistence.enabled=false \
  --set minio.mode=standalone \
  --set minio.replicas=1 \
  --set pulsar.enabled=false \
  --set pulsarv3.enabled=false \
  --set standalone.podAnnotations."sidecar\.istio\.io/inject"="false"

验证连接：

from pymilvus import connections
connections.connect("default", host="my-release-milvus.docs-agent.svc.cluster.local", port="19530")
print("Connected to Milvus successfully!")

再部署 KServe 的 ServingRuntime 与 InferenceService（模型 RedHatAI/Llama-3.1-8B-Instruct，vLLM 后端，需要 huggingface-secret 中的 HF_TOKEN）：

apiVersion: serving.kserve.io/v1alpha1
kind: ServingRuntime
metadata:
  name: llm-runtime
  namespace: docs-agent
spec:
  supportedModelFormats:
    - name: huggingface
      version: "1"
      autoSelect: true
  containers:
    - name: kserve-container
      image: kserve/huggingfaceserver:latest-gpu
      command: ["python", "-m", "huggingfaceserver"]
      resources:
        requests:
          cpu: "4"
          memory: "16Gi"
          nvidia.com/gpu: "1"
        limits:
          cpu: "6"
          memory: "24Gi"
          nvidia.com/gpu: "1"

若 Kubeflow Pipelines 需要访问 Milvus，还要补上 RBAC：

kubectl create role milvus-access \
  --namespace docs-agent \
  --verb=get,list,watch \
  --resource=services,endpoints

kubectl create rolebinding kfp-to-milvus-editor \
  --namespace docs-agent \
  --role=milvus-access \
  --serviceaccount=kubeflow:default-editor

完整平台（Knative、Istio、KServe、KFP、Milvus、kagent、网关护栏）由 docs-agent-mcp/terraform 下的配置声明式创建，路径上的具体变量名与凭据配置仓库未逐条列出，需要按 variables.tf 与 kagent.tf 自行补齐。

如何使用这个 Agent？

运行数据接入流水线，把文档写入 Milvus：

python docs-agent-mcp/pipelines/kubeflow-pipeline.py

启动 API 服务（WebSocket 或 HTTPS 二选一）：

# WebSocket API
python server/app.py

# HTTPS API
python server-https/app.py

流式调用（Server-Sent Events）：

curl -X POST "https://your-domain.com/chat" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"message": "What is KServe?", "stream": true}'

非流式调用：

curl -X POST "https://your-domain.com/chat" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is KServe?", "stream": false}'

import requests
import json

response = requests.post(
    'https://your-domain.com/chat',
    json={
        'message': 'What is KServe?',
        'stream': False
    }
)

data = response.json()
print(f"Response: {data['response']}")
if data.get('citations'):
    print(f"Sources: {data['citations']}")

常用环境变量：KSERVE_URL、MODEL（默认 llama3.1-8B）、PORT（默认 8000）、MILVUS_HOST、MILVUS_PORT（默认 19530）、MILVUS_COLLECTION（默认 kubeflow_docs）、EMBEDDING_MODEL（默认 sentence-transformers/all-mpnet-base-v2）。流水线参数包括 repo_owner、repo_name、directory_path（默认 content/en）、chunk_size（1000）、chunk_overlap（100）、base_url、milvus_host。排查可用：

kubectl get pods -n docs-agent | grep milvus
kubectl get inferenceservice -n docs-agent
kubectl logs -f deployment/docs-assistant-api

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

常见问题