安装 Llama Stack

本文档介绍如何使用 Llama Stack operator 在 Kubernetes 上安装并部署 Llama Stack Server。

上传 Operator

下载 Llama Stack operator 安装文件(例如 llama-stack-operator.alpha.ALL.xxxx.tgz)。

使用 violet 命令发布到平台仓库:

violet push --platform-address=platform-access-address --platform-username=platform-admin --platform-password=platform-admin-password llama-stack-operator.alpha.ALL.xxxx.tgz

安装 Operator

  1. 在 Alauda Container Platform 中进入 Administrator 视图。

  2. 在左侧导航中,选择 Marketplace / Operator Hub。

  3. 在右侧面板中,找到 Alauda build of Llama Stack 并单击 Install。

  4. 保持所有参数为默认值并完成安装。

部署 Llama Stack Server

在 operator 安装完成后,通过创建 LlamaStackDistribution 自定义资源来部署 Llama Stack Server:

注意: 请提前准备以下内容;否则 distribution 可能不会就绪:

  • 推理 URL:VLLM_URL 必须指向一个 vLLM OpenAI-compatible HTTP 基础 URL(例如集群内的 vLLM 或 KServe InferenceService),该 URL 需要提供目标模型服务。
  • Secret(可选):只有当 vLLM 端点需要认证时,才需要 VLLM_API_TOKEN。如果 vLLM 没有认证,请不要设置它。若需要,请在同一命名空间中创建一个 Secret,并在 containerSpec.env 中引用它(请参见下方清单中的注释示例)。
  • Storage Class:确保集群中存在 default Storage Class;否则 PVC 无法绑定,资源也不会就绪。
  • PGVector(可选):若要使用 provider_id="pgvector" 的 vector_stores,请为服务器 pod 提供 PGVECTOR_* 环境变量。ACP 提供的 PostgreSQL 可以直接使用,因为它已包含 pgvector 扩展。
  • Embedding 模型下载:Llama Stack 为 vector-store 用法提供了默认的 embedding 模型配置,但模型工件会在首次使用时从 Hugging Face 下载。如果需要镜像或代理,请配置 HF_ENDPOINT。对于完全离线的环境,请在运行首次 vector-store 请求之前,将模型文件预下载到服务器 PVC 中。
apiVersion: llamastack.io/v1alpha1
kind: LlamaStackDistribution
metadata:
  annotations:
    cpaas.io/display-name: ""
  name: demo
  namespace: default
spec:
  network:
    exposeRoute: false                             # Whether to expose the route externally
  replicas: 1                                      # Number of server replicas
  server:
    containerSpec:
      name: llama-stack
      port: 8321
      env:
        - name: VLLM_URL
          value: "http://vllm-predictor.default.svc.cluster.local/v1"   # vLLM OpenAI-compatible base URL
        - name: VLLM_MAX_TOKENS
          value: "8192"                            # Maximum output tokens

        # Optional: VLLM_API_TOKEN — add only when the vLLM endpoint requires authentication.
        # If vLLM is deployed without auth, omit the entire block below (do not set VLLM_API_TOKEN).
        # Example after creating: kubectl create secret generic vllm-api-token -n default --from-literal=token=<TOKEN>
        # - name: VLLM_API_TOKEN
        #   valueFrom:
        #     secretKeyRef:
        #       key: token
        #       name: vllm-api-token

        # Optional: enable PGVector-backed vector stores.
        # Omit the entire block below if you do not need vector store APIs.
        # ACP-provided PostgreSQL already includes the pgvector extension.
        # - name: ENABLE_PGVECTOR
        #   value: "true"
        # - name: PGVECTOR_HOST
        #   value: "<acp-postgresql-service>"
        # - name: PGVECTOR_PORT
        #   value: "5432"
        # - name: PGVECTOR_DB
        #   value: "<database-name>"
        # - name: PGVECTOR_USER
        #   value: "<database-username>"
        # - name: PGVECTOR_PASSWORD
        #   valueFrom:
        #     secretKeyRef:
        #       name: <pgvector-credentials-secret>
        #       key: password

        # Optional: configure a Hugging Face mirror or proxy for the default
        # embedding model download path.
        # - name: HF_ENDPOINT
        #   value: "<huggingface-mirror-or-proxy>"
        #
        # Optional: configure fully offline model loading. Pre-populate the
        # Hugging Face cache under /home/lls/.lls/huggingface/hub, then set:
        # - name: HF_HUB_CACHE
        #   value: "/home/lls/.lls/huggingface/hub"
        # - name: HF_HUB_OFFLINE
        #   value: "1"
        # - name: TRANSFORMERS_OFFLINE
        #   value: "1"
        # - name: HF_HUB_DISABLE_XET
        #   value: "1"

    distribution:
      name: starter                                # Distribution name (options: starter, postgres-demo, meta-reference-gpu)
    storage:
      mountPath: /home/lls/.lls
      size: 1Gi                                    # Requires the "default" Storage Class to be configured beforehand

部署完成后,Llama Stack Server 将可在集群内部访问。访问 URL 显示在 status.serviceURL 中,例如:

status:
  phase: Ready
  serviceURL: http://demo-service.default.svc.cluster.local:8321

在 KServe 上使用 vLLM 进行 tool 调用

以下内容适用于 KServe 上的 vLLM predictor,不适用于 LlamaStackDistribution 清单。对于使用 tools(客户端工具或 MCP)的 agent 流程,vLLM 进程必须暴露 tool-call 支持。请根据上游 vLLM 的要求为 predictor 容器添加 args,例如:

args:
  - --enable-auto-tool-choice
  - --tool-call-parser
  - hermes

请根据 served model 以及该模型族的 vLLM 文档选择 --tool-call-parser(以及任何相关标志)。

启用 PGVector Vector Store

当服务器上设置了 ENABLE_PGVECTOR=true 时,Llama Stack 可以通过客户端 API 使用 provider_id="pgvector" 创建 vector stores。

建议准备步骤:

  1. 准备一个 ACP PostgreSQL 实例,并记录其服务名称、数据库名称、用户名和密码。
  2. 使用 PGVECTOR_HOST、PGVECTOR_PORT、PGVECTOR_DB、PGVECTOR_USER 和 PGVECTOR_PASSWORD 将数据库连接暴露给 LlamaStackDistribution。
  3. 使用 Llama Stack 提供的默认 embedding 模型,并确保其模型文件可在首次使用时获取。
  4. 如果集群使用 Hugging Face 镜像或代理,请相应设置 HF_ENDPOINT。
  5. 如果集群完全离线,请将 embedding 模型文件预下载到服务器 PVC 中,并启用与离线缓存相关的环境变量。

当 distribution 就绪后,您可以使用 Quickstart notebook 中的 PGVector 部分来验证配置。

Embedding 模型的 Hugging Face 访问

Llama Stack 为 vector-store 操作使用默认的 embedding 模型。首次使用时,服务器会将模型文件从 Hugging Face 下载到本地缓存中。

推荐的缓存路径:

  • /home/lls/.lls/huggingface/hub

常见部署模式:

  1. 镜像或代理访问:

    - name: HF_ENDPOINT
      value: "<huggingface-mirror-or-proxy>"
    - name: HF_HUB_CACHE
      value: "/home/lls/.lls/huggingface/hub"
  2. 完全离线访问:

    先将所需模型文件预下载到 PVC 支持的缓存目录 /home/lls/.lls/huggingface/hub,然后设置:

    - name: HF_HUB_CACHE
      value: "/home/lls/.lls/huggingface/hub"
    - name: HF_HUB_OFFLINE
      value: "1"
    - name: TRANSFORMERS_OFFLINE
      value: "1"
    - name: HF_HUB_DISABLE_XET
      value: "1"

如果缓存路径已正确预填充,服务器就可以在运行时不下载模型工件的情况下创建基于 PGVector 的 vector stores。