安装 Llama Stack

在 Alauda AI 2.8.x 中，Alauda Build of Llama Stack 由 Alauda AI 安装和管理。集群级 default AmlCluster 中的 llamaStack 组件默认值为 Unmanaged；将其设置为 Managed 后，您无需手动从 OperatorHub 安装 Operator。组件完成 reconcile 后，按照下文所述，通过 LlamaStackDistribution 自定义资源部署 Llama Stack Server。

上传 Operator 包

下载 Llama Stack Operator 包，然后按照上架软件包上架该包。

启用 Llama Stack

在 Administrator 视图中：

打开 Marketplace > OperatorHub。
选择目标集群并打开 Alauda AI。
打开 All Instances 选项卡，编辑 default AmlCluster 实例。
将 spec.components.llamaStack.managementState 设置为 Managed。
保存 AmlCluster 实例，并等待 Llama Stack Operator 变为 ready。

您可以在 AmlCluster YAML 中应用该组件设置：

spec:
  components:
    llamaStack:
      managementState: Managed

验证安装

检查 AmlCluster 状态和 Llama Stack Operator：

kubectl get amlcluster default

kubectl get pods -n llama-stack-k8s-operator-system

AmlCluster 应返回 Phase=Ready，并且 Llama Stack Operator controller pod 应处于 Running 状态。Operator ready 后，系统会注册 LlamaStackDistribution CRD。

部署 Llama Stack Server

安装 Operator 后，通过创建 LlamaStackDistribution 自定义资源来部署 Llama Stack Server：

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

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

Secret（可选）：仅当 vLLM endpoint 需要认证时才需要 VLLM_API_TOKEN。如果 vLLM 没有认证，请勿设置。若需要，请在同一 namespace 中创建一个 Secret，并在 containerSpec.env 中引用它（请参见下方 manifest 中的注释示例）。

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

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 model 下载：Llama Stack 为 vector-store 用法提供了默认的 embedding model 配置，但模型制品会在首次使用时从 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 vector-store provider 的 PGVECTOR_*。如果同一个 PostgreSQL 实例具备所需的数据库、凭据和 pgvector 扩展，您可以将其同时用于这两种角色。

在 KServe 上使用 vLLM 进行 tool calling

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

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

请根据 served model 以及该模型家族对应的 vLLM 文档，选择 --tool-call-parser（以及任何相关参数）。

启用 PGVector Vector Store

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

建议准备步骤：

准备一个 ACP PostgreSQL 实例，并记录其 service name、database name、username 和 password。
使用 PGVECTOR_HOST、PGVECTOR_PORT、PGVECTOR_DB、PGVECTOR_USER 和 PGVECTOR_PASSWORD 将数据库连接信息暴露给 LlamaStackDistribution。
设置 ENABLE_SENTENCE_TRANSFORMERS=true，并确保默认 embedding model 文件能够在首次使用时被获取。
如果集群使用 Hugging Face 镜像或代理，请相应设置 HF_ENDPOINT。
如果集群完全离线，请预先将 embedding model 文件下载到 server PVC 中，并启用与离线缓存相关的环境变量。

distribution 变为 ready 后，您可以使用 Quickstart notebook 中的 PGVector 部分验证该配置。

启用 Milvus Vector Store

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

建议准备步骤：

准备一个 Llama Stack Server pod 可访问的 Milvus endpoint。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 model 文件可以被获取或已经存在于 server PVC 中。

distribution 变为 ready 后，使用 Quickstart notebook 中的 Milvus 部分验证该配置。client 会使用 provider_id="milvus-remote" 创建 vector store，并在 extra_body 中传递所选的 embedding model id 以及 embedding dimension。

Hugging Face 访问用于 embedding models

Llama Stack 在 vector-store 操作中使用默认的 embedding model。首次使用时，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 包

#启用 Llama Stack

#验证安装

#部署 Llama Stack Server

#配置 PostgreSQL 存储

#在 KServe 上使用 vLLM 进行 tool calling

#启用 PGVector Vector Store

#启用 Milvus Vector Store

#Hugging Face 访问用于 embedding models