配置“堆栈”

Llama Stack 运行时配置由 YAML 文件指定。以下是 Ollama 分发版的一个简化示例配置文件版本

让我们将其分解为不同的部分。第一部分指定了堆栈服务器将提供的 API 集合

apis:
- agents
- inference
- memory
- safety
- telemetry

提供者

接下来是最关键的部分：堆栈将用于提供上述 API 的提供者集合。考虑推理 API

providers:
  inference:
  # provider_id is a string you can choose freely
  - provider_id: ollama
    # provider_type is a string that specifies the type of provider.
    # in this case, the provider for inference is ollama and it is run remotely (outside of the distribution)
    provider_type: remote::ollama
    # config is a dictionary that contains the configuration for the provider.
    # in this case, the configuration is the url of the ollama server
    config:
      url: ${env.OLLAMA_URL:http://localhost:11434}

需要注意的几点

提供者实例由一个 (id, 类型, 配置) 三元组标识。
id 是一个您可以自由选择的字符串。
您可以实例化任意数量的相同类型的提供者实例。
配置字典是提供者特定的。
注意，配置可以引用环境变量（带有默认值），这些变量在运行时展开。当您运行堆栈服务器（通过 docker 或通过 llama stack run）时，您可以指定 --env OLLAMA_URL=http://my-server:11434 来覆盖默认值。

资源

最后，让我们看看 models 部分

models:
- metadata: {}
  model_id: ${env.INFERENCE_MODEL}
  provider_id: ollama
  provider_model_id: null

模型是“资源”（参见概念）的一个实例，并且与特定的推理提供者相关联（在本例中，是标识符为 ollama 的提供者）。这是一个“预注册”模型的实例。虽然我们始终鼓励客户端在使用模型之前注册它们，但某些堆栈服务器可能会提供一个“已知且可用”模型的列表。

provider_model_id 字段是什么意思？这是提供者模型目录中模型的标识符。将其与 model_id 对比，后者是 Llama Stack 用于标识同一模型的标识符。例如，您可能希望在堆栈交互中使用“llama3.2:vision-11b”时将其命名为“image_captioning_model”。如果省略，服务器会将 provider_model_id 设置为与 model_id 相同。

服务器配置

server 部分配置提供 Llama Stack API 的 HTTP 服务器

server:
  port: 8321  # Port to listen on (default: 8321)
  tls_certfile: "/path/to/cert.pem"  # Optional: Path to TLS certificate for HTTPS
  tls_keyfile: "/path/to/key.pem"    # Optional: Path to TLS key for HTTPS
  auth:                              # Optional: Authentication configuration
    provider_type: "kubernetes"      # Type of auth provider
    config:                          # Provider-specific configuration
      api_server_url: "https://kubernetes.default.svc"
      ca_cert_path: "/path/to/ca.crt" # Optional: Path to CA certificate

身份验证配置

auth 部分配置服务器的身份验证。配置后，所有 API 请求必须在 Authorization 头部包含有效的 Bearer 令牌

Authorization: Bearer <token>

服务器支持多种身份验证提供者

Kubernetes 提供者

Kubernetes 集群必须配置为使用服务帐户进行身份验证。

kubectl create namespace llama-stack
kubectl create serviceaccount llama-stack-auth -n llama-stack
kubectl create rolebinding llama-stack-auth-rolebinding --clusterrole=admin --serviceaccount=llama-stack:llama-stack-auth -n llama-stack
kubectl create token llama-stack-auth -n llama-stack > llama-stack-auth-token

根据 Kubernetes API 服务器验证令牌

server:
  auth:
    provider_type: "kubernetes"
    config:
      api_server_url: "https://kubernetes.default.svc"  # URL of the Kubernetes API server
      ca_cert_path: "/path/to/ca.crt"                   # Optional: Path to CA certificate

提供者从 JWT 令牌中提取用户信息

sub 声明中的用户名成为一个角色
Kubernetes 组成为团队

您可以通过运行以下命令轻松验证请求

curl -s -L -H "Authorization: Bearer $(cat llama-stack-auth-token)" http://127.0.0.1:8321/v1/providers

自定义提供者

根据自定义身份验证端点验证令牌

server:
  auth:
    provider_type: "custom"
    config:
      endpoint: "https://auth.example.com/validate"  # URL of the auth endpoint

自定义端点接收一个 POST 请求，包含

{
  "api_key": "<token>",
  "request": {
    "path": "/api/v1/endpoint",
    "headers": {
      "content-type": "application/json",
      "user-agent": "curl/7.64.1"
    },
    "params": {
      "key": ["value"]
    }
  }
}

并且必须响应

{
  "access_attributes": {
    "roles": ["admin", "user"],
    "teams": ["ml-team", "nlp-team"],
    "projects": ["llama-3", "project-x"],
    "namespaces": ["research"]
  },
  "message": "Authentication successful"
}

如果没有返回访问属性，则令牌用作命名空间。

扩展以处理安全

配置安全可能有点复杂，因此通过一个示例进行讲解很有帮助。

Safety API 与称为 Shield 的相关资源一起工作。提供者可以支持各种类型的 Shield。好的示例包括 Llama Guard 系统安全模型或 Bedrock Guardrails。

要配置 Bedrock Shield，您需要添加

一个类型为 remote::bedrock 的 Safety API 提供者实例
由该提供者提供服务的 Shield 资源。

...
providers:
  safety:
  - provider_id: bedrock
    provider_type: remote::bedrock
    config:
      aws_access_key_id: ${env.AWS_ACCESS_KEY_ID}
      aws_secret_access_key: ${env.AWS_SECRET_ACCESS_KEY}
...
shields:
- provider_id: bedrock
  params:
    guardrailVersion: ${env.GUARDRAIL_VERSION}
  provider_shield_id: ${env.GUARDRAIL_ID}
...

如果 Shield 需要关联模型的推理，情况会更复杂。Llama Guard 就是这种情况。在这种情况下，您需要添加

一个类型为 inline::llama-guard 的 Safety API 提供者实例
一个用于提供模型服务的 Inference API 提供者实例。
与此提供者关联的 Model 资源。
由 Safety 提供者提供服务的 Shield 资源。

假设您使用 vLLM 作为推理服务器，则此设置的 yaml 配置如下所示

...
providers:
  safety:
  - provider_id: llama-guard
    provider_type: inline::llama-guard
    config: {}
  inference:
  # this vLLM server serves the "normal" inference model (e.g., llama3.2:3b)
  - provider_id: vllm-0
    provider_type: remote::vllm
    config:
      url: ${env.VLLM_URL:http://localhost:8000}
  # this vLLM server serves the llama-guard model (e.g., llama-guard:3b)
  - provider_id: vllm-1
    provider_type: remote::vllm
    config:
      url: ${env.SAFETY_VLLM_URL:http://localhost:8001}
...
models:
- metadata: {}
  model_id: ${env.INFERENCE_MODEL}
  provider_id: vllm-0
  provider_model_id: null
- metadata: {}
  model_id: ${env.SAFETY_MODEL}
  provider_id: vllm-1
  provider_model_id: null
shields:
- provider_id: llama-guard
  shield_id: ${env.SAFETY_MODEL}   # Llama Guard shields are identified by the corresponding LlamaGuard model
  provider_shield_id: null
...