安装 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

进入 Alauda Container Platform 中的 管理员 视图。
在左侧导航中，选择 Marketplace / Operator Hub。
在右侧图表中，找到 Alauda build of Llama Stack，然后单击 Install。
保持所有参数为默认值，完成安装。

部署 Llama Stack Server

在 operator 安装完成后，通过创建一个 LlamaStackDistribution 自定义资源来部署 Llama Stack Server：

注意：请提前准备以下内容；否则 distribution 可能无法就绪：

Inference URL：VLLM_URL 必须指向一个 vLLM OpenAI-compatible 的 HTTP 基础 URL（例如集群内的 vLLM 或 KServe InferenceService），并且该 URL 提供目标模型服务。

Secret（可选）：只有在 vLLM 端点需要认证时，才需要 VLLM_API_TOKEN。如果 vLLM 没有认证，请不要设置它。需要时，请在相同命名空间中创建 Secret，并在 containerSpec.env 中引用它（请参见下方 manifest 中的注释示例）。

Storage Class：确保集群中存在 default Storage Class；否则 PVC 无法绑定，资源也不会就绪。

PostgreSQL 存储：此版本中的 starter distribution 使用 PostgreSQL 作为 Llama Stack 的持久化存储。部署前，请为 server pod 配置 POSTGRES_* 环境变量。

PGVector（可选）：若要使用 provider_id="pgvector" 的 vector_stores，请为 server pod 提供 PGVECTOR_* 环境变量。ACP 提供的 PostgreSQL 可以直接使用，因为它已包含 pgvector 扩展。

Milvus（可选）：若要使用 provider_id="milvus-remote" 的 vector_stores，请提供 MILVUS_ENDPOINT，并在启用认证时提供 MILVUS_TOKEN。将 MILVUS_CONSISTENCY_LEVEL 设置为有效的 Milvus 一致性级别，例如 Strong。

Embedding 模型下载：Llama Stack 为 vector-store 使用提供了默认的 embedding 模型配置，但模型制品会在首次使用时从 Hugging Face 下载。如果需要镜像或代理，请配置 HF_ENDPOINT。对于完全离线的环境，请在首次 vector-store 请求之前，将模型文件预下载到 server 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

        # Required: PostgreSQL-backed Llama Stack persistence for this starter
        # distribution image.
        - name: POSTGRES_HOST
          value: "<postgresql-service>"
        - name: POSTGRES_PORT
          value: "5432"
        - name: POSTGRES_DB
          value: "<database-name>"
        - name: POSTGRES_USER
          value: "<database-username>"
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: <postgresql-credentials-secret>
              key: password

        # Optional: enable PGVector-backed vector stores.
        # Omit the entire block below if you do not need PGVector vector stores.
        # These settings configure the vector DB provider and are separate from
        # the POSTGRES_* persistence settings above, although they may point to
        # the same PostgreSQL instance when it has the pgvector extension.
        # 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: enable remote Milvus-backed vector stores.
        # Use provider_id="milvus-remote" from the client API.
        # - name: MILVUS_ENDPOINT
        #   value: "http://<milvus-endpoint-host-and-port>"
        # - name: MILVUS_TOKEN
        #   valueFrom:
        #     secretKeyRef:
        #       name: <milvus-credentials-secret>
        #       key: token
        # - name: MILVUS_CONSISTENCY_LEVEL
        #   value: "Strong"

        # Required for PGVector or Milvus vector stores that use local
        # sentence-transformers embeddings.
        # - name: ENABLE_SENTENCE_TRANSFORMERS
        #   value: "true"
        #
        # 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

配置 PostgreSQL 存储

此版本使用的 starter distribution 镜像要求 PostgreSQL 用于 Llama Stack 持久化。请在 LlamaStackDistribution 中配置以下 server 环境变量：

POSTGRES_HOST
POSTGRES_PORT
POSTGRES_DB
POSTGRES_USER
POSTGRES_PASSWORD

这些设置用于 Llama Stack server 状态。它们与 PGVECTOR_* 不同，后者仅用于配置可选的 PGVector vector-store provider。只要具备所需的数据库、凭据和 pgvector 扩展，就可以将同一个 PostgreSQL 实例同时用于这两种用途。

在 KServe 上使用 vLLM 进行 tool calling

以下内容适用于 KServe 上的 vLLM predictor，不适用于 LlamaStackDistribution manifest。对于使用 tools（客户端工具或 MCP）的 agent 流程，vLLM 进程必须暴露 tool-call 支持。请根据上游 vLLM 的要求为 predictor container 添加 args，例如：

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

请根据 所服务的模型 以及该模型家族对应的 vLLM 文档，选择 --tool-call-parser（以及任何相关标志）。

启用 PGVector Vector Store

当 server 上设置了 ENABLE_PGVECTOR=true 时，Llama Stack 可以通过客户端 API 使用 provider_id="pgvector" 创建 vector store。

建议准备步骤：

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

当 distribution 就绪后，可以在 Quickstart notebook 中使用 PGVector 部分验证配置。

启用 Milvus Vector Store

当 server 上设置了 MILVUS_ENDPOINT 时，Llama Stack 可以通过客户端 API 使用 provider_id="milvus-remote" 创建 vector store。

建议准备步骤：

准备一个从 Llama Stack Server pod 可访问的 Milvus 端点。MILVUS_ENDPOINT 必须包含 scheme，即 http:// 或 https://，并且要包含 Milvus 服务所需的端口。
通过 MILVUS_ENDPOINT 将 Milvus 连接暴露给 LlamaStackDistribution。
如果启用了 Milvus 认证，请从 Secret 中设置 MILVUS_TOKEN。
将 MILVUS_CONSISTENCY_LEVEL 设置为字符串值，例如 Strong；Milvus provider 需要此字段。
设置 ENABLE_SENTENCE_TRANSFORMERS=true，并确保 embedding 模型文件可以被获取，或者已存在于 server PVC 中。

当 distribution 就绪后，可以在 Quickstart notebook 中使用 Milvus 部分验证配置。客户端会使用 provider_id="milvus-remote" 创建 vector store，并在 extra_body 中传入所选的 embedding model id 以及 embedding 维度。

Hugging Face 访问 embedding 模型

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

推荐的缓存路径：

/home/lls/.lls/huggingface/hub

常见部署模式：

镜像或代理访问：

- name: HF_ENDPOINT
  value: "<huggingface-mirror-or-proxy>"
- name: HF_HUB_CACHE
  value: "/home/lls/.lls/huggingface/hub"

完全离线访问：

将所需的模型文件预下载到基于 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"

如果缓存路径已正确预填充，server 就可以在运行时创建基于 PGVector 或基于 Milvus 的 vector store，而无需下载模型制品。

#安装 Llama Stack

#目录

#上传 operator

#安装 operator

#部署 Llama Stack Server

#配置 PostgreSQL 存储

#在 KServe 上使用 vLLM 进行 tool calling

#启用 PGVector Vector Store

#启用 Milvus Vector Store

#Hugging Face 访问 embedding 模型