跳到正文
AWS Machine Learning Blog· Jyothirmai Kottu·· 2 小时前精选AI 评分61

在 Amazon SageMaker AI 上用 llama.cpp 部署决策模型

Deploy decision models with llama.cpp on Amazon SageMaker AI

AI 导读

AWS 发布教程，介绍如何用 AWS DLC for llama.cpp 在 Amazon SageMaker AI 上部署决策模型，通过 InvokeEndpoint 提供 OpenAI 兼容的 chat completions，并可用 SemIf 适配器直接返回声明选项的概率而非生成答案 token。

推荐理由

AWS 官方给出在 SageMaker AI 上用 llama.cpp 部署决策模型的完整路径，含 CPU 与 GPU 的实测延迟对比。

正文 · AI 翻译

路由请求、选择智能体操作或分配策略结果的应用，通常需要对一组固定选项进行评分，而不是自由形式的文本。使用 llama.cpp 在 Amazon SageMaker AI 上部署这些决策模型，为您提供了一条在 CPU 或 GPU 基础设施上服务量化模型的托管路径。

本文延续了关于用于生成式 AI 推理的专用 AWS 深度学习容器（DLC）系列。之前的文章涵盖了 WhisperX、vLLM-Omni – 第 1 部分 和 vLLM-Omni – 第 2 部分。

在本文中，您首先使用 AWS DLC for llama.cpp 通过 SageMaker AI InvokeEndpoint 提供与 OpenAI 兼容的聊天补全。然后，您使用 SemIf（前身为 OpenJev）扩展同一运行时，它在不生成答案 token 的情况下返回对声明选项的概率。随附的 代码示例 包含 CPU 和 GPU 部署选项。

解决方案概述

图 1 显示了来自同一打包模型的两种部署路径。文本生成路径使用 AWS DLC for llama.cpp，并通过与 OpenAI 兼容的 API 返回生成的响应。结构化决策路径构建一个子镜像，用 SemIf 适配器替换默认服务器，并返回声明选项的概率。

An application invokes an Amazon SageMaker AI real-time endpoint that can use the AWS Deep Learning Container for llama.cpp for generated text or a SemIf child image for option probabilities. Either serving mode can run on CPU or GPU.

图 1：根据工作负载的 API 和延迟要求，在 CPU 或 GPU 上运行 AWS DLC for llama.cpp 或 SemIf 子镜像

对于标准路径，将模型打包为 Amazon Simple Storage Service (Amazon S3) 中的 model.tar.gz，并直接引用已发布的 DLC 镜像。容器在 /opt/ml/model 下找到第一个 .gguf 文件，将 POST /invocations 映射到 /v1/chat/completions 处的 llama-server，并将 SM_LLAMA_CPP_* 环境变量传递给 llama.cpp 参数。

llama-server HTTP API 不暴露 SemIf 使用的最终位置 logits 和状态操作。因此，结构化决策路径使用 AWS CodeBuild 构建子镜像并将其存储在 Amazon Elastic Container Registry (Amazon ECR) 中。子镜像保留 DLC 编译的 CPU 或 CUDA 库，同时用与 SageMaker 兼容的适配器替换其入口点。

理解输入和输出模式

AWS DLC for llama.cpp 接受 OpenAI Chat Completions 模式。发送一个包含 role 和 content 的 messages 数组，以及生成控制参数，如 max_tokens 和 stream：

{
  "messages": [
    {
      "role": "user",
      "content": "A customer cannot receive a password reset email. Reply with the best support queue."
    }
  ],
  "max_tokens": 64,
  "stream": false
}

响应使用与 OpenAI 兼容的 choices 数组。从 choices[0].message.content 读取生成的文本。

SemIf 使用受限决策模式而不是聊天消息。请求包含调用方定义的 ID、非结构化状态、一个问题以及允许选项的有序列表：

{
  "decision": {
    "id": "support-route",
    "state": "The customer cannot receive a password reset email.",
    "question": "Which queue should handle this request?",
    "options": [
      {"id": "account_access", "description": "Account access support."},
      {"id": "billing", "description": "Billing support."}
    ]
  }
}

响应按相同顺序返回 option_ids、probabilities 和原始 option_logits，以及提示、计时和固定模型元数据。使用稳定的选项 ID，您的应用可以应用阈值、回退和策略检查，而无需解析生成的文本。

SemIf 属于更广泛的决策模型类别，这些模型从非结构化状态中对应用定义的结果进行评分。其他实现包括 Jev、TypeSafe 的决策模型和 /v1/systemone API；Kev，一个为 TypeSafe API 兼容性设计的模型服务器；以及 Strands Decider 2B，一个专为智能体工作流构建的模型，具有校准输出。

选择合适的决策工作流

当你的应用在请求时定义允许的选项，并需要模型解释非结构化上下文时，请使用此模式。示例包括将案例路由到队列、从已知集合中提取一个值、分配事件优先级、检查策略结果或选择代理操作。将授权和确定性业务规则保留在模型之外，并在将模型概率视为操作置信度之前对其进行验证。

当你需要通过 InvokeEndpoint 获得 OpenAI 兼容的聊天补全时，请使用标准 SageMaker AI 文本生成路径。SageMaker AI 镜像将 POST /invocations 映射到 llama-server /v1/chat/completions 端点。仅当你的应用需要此接口未提供的行为（例如 SemIf 的直接 logits 和状态访问）时，才构建子镜像。

移除答案 token 生成并不会移除模型推理。在 SemIf 读取最终 logits 之前，模型仍会处理完整的状态、问题和选项描述。保持提示词聚焦，并在生产使用前用你应用中的带标签决策评估所选模型。

针对你的延迟和质量目标进行调优

以下基准测试适用于 SemIf 扩展，而非文本生成端点。模型大小、量化、提示词长度、运行时和 CPU 线程数都会影响每次决策。为了量化这些权衡，我们将相同的 231 个公开 JevBench 任务串行发送到一个 CPU 端点和一个 GPU 端点。

配置 用于 llama.cpp 的 AWS DLC 有效响应 准确率 客户端 p50 客户端 p95
Qwen3.5-4B Q4_K_M、ml.c6i.8xlarge、32 线程 llama-cpp:server-sagemaker-cpu-v1 231/231 179/231 (77.5%) 1.715 秒 19.291 秒
Qwen3.5-4B Q4_K_M、ml.g6e.xlarge、完整 GPU 卸载 llama-cpp:server-sagemaker-cuda-v1 231/231 180/231 (77.9%) 0.352 秒 0.599 秒

与 CPU 配置相比，GPU 端点在 p50 上快 4.9 倍，在 p95 上快 32.2 倍。该示例使用 SageMaker AI 实例池功能按优先级顺序列出兼容的 GPU 实例类型，以便 SageMaker 在首选实例不可用时选择替代实例。实例池的顺序为 g6e、g6、g5，然后是 g4dn。SageMaker 选择了 ml.g6e.xlarge，启动日志确认 llama.cpp 将所有 34 个模型层卸载到 NVIDIA L40S。CPU 和 GPU 镜像使用了不同的 llama.cpp 构建，并在六个困难任务上产生了不同的预测。请将单答案准确率差异视为运行时差异，而非 GPU 卸载提升模型质量的证据。

更小的模型降低了中位延迟，但 2B 和 0.8B 候选模型分别仅达到 66.7% 和 58.4% 的准确率。因此，该示例保留 4B Q4_K_M 模型作为其质量优先的默认选项。这些测量包含网络延迟，并非服务保证。

针对你自己的决策对完整模型和基础设施配置进行基准测试。对于不延迟敏感且能容忍数秒响应时间的后台、离线或低吞吐量工作负载，请使用 CPU。对于交互式决策、长提示词或具有严格尾部延迟目标的工作负载，请使用 GPU。保持状态和选项描述简洁，将共享相同状态的决策分组到一个请求中，并为并发扩展端点实例。共享状态评分会复用公共提示词前缀，而适配器会返回可重试的 HTTP 503 响应，而不是在其有状态的 llama.cpp 上下文周围允许无界队列。

先决条件

你需要：

  • 一个 AWS 账户，以及位于您部署 AWS 区域中的 S3 存储桶。
  • Python 3.10 或更高版本、Git 以及 AWS 命令行界面（AWS CLI）。
  • 一个专用于可选 SemIf 扩展的 CodeBuild 服务角色。
  • 一个 SageMaker AI 可以代入的 AWS Identity and Access Management (IAM) 角色。
  • SageMaker AI、Amazon ECR、Amazon S3、CodeBuild、IAM 传递角色操作以及 Amazon CloudWatch Logs 的权限。
  • 兼容的 x86 CPU 或 NVIDIA GPU SageMaker 实时端点的配额。

文本生成示例使用 CPU DLC 和固定 CPU 实例。SemIf 扩展对延迟不敏感的工作负载默认保留 CPU，并提供带有有序实例池的可选 CUDA 镜像。在创建端点之前，请查看 SageMaker AI 定价。

部署决策模型并使用 SemIf 对其进行扩展

使用以下过程部署标准文本生成端点，然后为 CPU 或 GPU 上的结构化决策构建可选的 SemIf 扩展。

  1. Clone the code sample and install its dependencies. 
    git clone https://github.com/aws-samples/sagemaker-genai-hosting-examples.git
cd sagemaker-genai-hosting-examples/03-features/semif-decision-model
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -r deploy/requirements.txt
  2. Set the deployment values for your account. 
    export AWS_REGION="<your-region>"
export ARTIFACT_BUCKET=amzn-s3-demo-semif-artifacts
export CODEBUILD_ROLE_ARN=arn:aws:iam::111122223333:role/semif-codebuild-role
export SAGEMAKER_ROLE_ARN=arn:aws:iam::111122223333:role/semif-sagemaker-role
export STANDARD_ENDPOINT_NAME=llamacpp-gguf
export SEMIF_ENDPOINT_NAME=semif-decision-workflows
  3. Package the pinned GGUF model and tokenizer with CodeBuild. 
    python deploy/prepare_model_build.py \
  --region "$AWS_REGION" \
  --bucket "$ARTIFACT_BUCKET" \
  --codebuild-role-arn "$CODEBUILD_ROLE_ARN" \
  --model-s3-uri "s3://$ARTIFACT_BUCKET/semif-llamacpp/model.tar.gz"

    等待返回的构建 ID 达到 SUCCEEDED。构建会在 model-manifest.json 中记录源修订和校验和，如果 GGUF 校验和与已验证的值不同，则停止。

  4. Deploy the GGUF model with the AWS DLC for llama.cpp.

    从 AWS DLC for llama.cpp 文档 中解析出固定摘要的 server-sagemaker-cpu-v1 镜像，然后创建 SageMaker AI 模型、端点配置和端点：

    export STANDARD_IMAGE_URI="<published-llama-cpp-cpu-image>@sha256:<digest>"

python deploy/deploy_standard_endpoint.py \
  --region "$AWS_REGION" \
  --image-uri "$STANDARD_IMAGE_URI" \
  --model-data-url "s3://$ARTIFACT_BUCKET/semif-llamacpp/model.tar.gz" \
  --role-arn "$SAGEMAKER_ROLE_ARN" \
  --instance-type ml.c6i.2xlarge \
  --name "$STANDARD_ENDPOINT_NAME"

    选择 server-sagemaker-cpu-v1 或 server-sagemaker-cuda-v1 镜像，而不是对应的 EC2 镜像。SageMaker AI 镜像实现了 /ping 和 /invocations 容器契约，并将调用负载映射到聊天补全。

    本演练通过 Amazon S3 中的 SageMaker AI 模型构件提供 GGUF 模型。作为替代方案，您可以配置 SM_LLAMA_CPP_HF_REPO 和 SM_LLAMA_CPP_HF_FILE，在端点具有网络出口时从 Hugging Face 下载 GGUF 文件。

    此路径不需要 Dockerfile 或 ECR 存储库。等待端点进入 InService，然后发送 OpenAI 兼容的聊天请求：

    python deploy/invoke_standard_endpoint.py \
  --region "$AWS_REGION" \
  --endpoint-name "$STANDARD_ENDPOINT_NAME"
  5. Build the optional SemIf child image and resolve its immutable digest.

    对于 CPU：

    python deploy/prepare_build.py \
  --region "$AWS_REGION" \
  --bucket "$ARTIFACT_BUCKET" \
  --codebuild-role-arn "$CODEBUILD_ROLE_ARN"

    对于 GPU，改为构建 CUDA 子镜像：

    python deploy/prepare_build.py \
  --region "$AWS_REGION" \
  --bucket "$ARTIFACT_BUCKET" \
  --codebuild-role-arn "$CODEBUILD_ROLE_ARN" \
  --dockerfile Dockerfile.gpu \
  --image-tag "gpu-$(date +%Y%m%d%H%M%S)"

    构建成功后，构造不可变镜像 URI：

    ECR_REPOSITORY_URI=$(aws ecr describe-repositories \
  --region "$AWS_REGION" \
  --repository-names semif-llamacpp-dlc \
  --query 'repositories[0].repositoryUri' \
  --output text)
IMAGE_DIGEST=$(aws ecr describe-images \
  --region "$AWS_REGION" \
  --repository-name semif-llamacpp-dlc \
  --query 'sort_by(imageDetails,&imagePushedAt)[-1].imageDigest' \
  --output text)
export IMAGE_URI="${ECR_REPOSITORY_URI}@${IMAGE_DIGEST}"

    部署脚本会拒绝可变镜像标签。

  6. Deploy the SemIf endpoint.

    CPU 配置使用固定实例类型：

    python deploy/deploy_endpoint.py \
  --region "$AWS_REGION" \
  --image-uri "$IMAGE_URI" \
  --model-data-url "s3://$ARTIFACT_BUCKET/semif-llamacpp/model.tar.gz" \
  --role-arn "$SAGEMAKER_ROLE_ARN" \
  --instance-type ml.c6i.8xlarge \
  --threads 32 \
  --name "$SEMIF_ENDPOINT_NAME"

    等待返回的端点名称进入 InService。此路径设置 n_gpu_layers=0。适配器围绕一个有状态的 llama.cpp 上下文序列化评分，因此在测量工作负载后，通过端点实例进行横向扩展，而不是假设在一个容器内并行评分。

    对于 GPU 镜像，提供有序实例池并请求完全模型卸载：

    python deploy/deploy_endpoint.py \
  --region "$AWS_REGION" \
  --image-uri "$IMAGE_URI" \
  --model-data-url "s3://$ARTIFACT_BUCKET/semif-llamacpp/model.tar.gz" \
  --role-arn "$SAGEMAKER_ROLE_ARN" \
  --instance-pool ml.g6e.xlarge \
  --instance-pool ml.g6.2xlarge \
  --instance-pool ml.g5.2xlarge \
  --instance-pool ml.g4dn.2xlarge \
  --gpu-layers=-1 \
  --provision-timeout 1200 \
  --name "$SEMIF_ENDPOINT_NAME"

    实例池是有序的放置回退，而不是推理负载均衡。SageMaker 会为该变体选择一个可用类型。当 SageMaker AI 遍历池时，端点创建可能需要更长时间。检查启动日志以了解所选 GPU 以及确认所有模型层均已卸载的消息。

  7. Invoke the SemIf endpoint with the example decision.

    请求为每个允许的选项声明稳定的 ID：

    {
  "decision": {
    "id": "support-route",
    "state": "Customer asks to reset a forgotten password and says the reset email never arrived.",
    "question": "Which queue should handle this request?",
    "options": [
      {"id": "account_access", "description": "Account access and authentication support."},
      {"id": "billing", "description": "Billing and payment support."},
      {"id": "sales", "description": "Sales and product evaluation."}
    ]
  }
}
    python deploy/invoke_endpoint.py \
  --region "$AWS_REGION" \
  --endpoint-name "$SEMIF_ENDPOINT_NAME"

    响应保留选项顺序，并包含条件概率、原始 logits、token 和提示元数据以及固定的模型标识：

    {
  "result": {
    "id": "support-route",
    "option_ids": ["account_access", "billing", "sales"],
    "probabilities": [0.99996, 0.00003, 0.00001],
    "option_logits": [28.47, 17.92, 17.04],
    "prompt_sha256": "016267542103ab91422c425d2234ec7e1b9aef77f9d3e481b96db2de7cca470a",
    "readout": "quantized last-position logits restricted to declared answer slots; no generated tokens"
  }
}

    应用应用程序级阈值和回退。不要使用模型决策作为授权的替代品。

清理

删除 SageMaker AI 端点、端点配置和模型：

python deploy/cleanup_endpoint.py \
  --region "$AWS_REGION" \
  --name "$STANDARD_ENDPOINT_NAME"

python deploy/cleanup_endpoint.py \
  --region "$AWS_REGION" \
  --name "$SEMIF_ENDPOINT_NAME"

该脚本仅删除那些显式命名的 SageMaker AI 资源。当您不再需要时，删除 CodeBuild 项目、ECR 存储库、Amazon S3 中的模型和源对象、日志以及专用 IAM 角色。

结论

llama.cpp 的 AWS DLC 为你提供了一个托管基础，用于在 SageMaker AI 上跨 CPU 和 GPU 实例为决策模型提供服务。它可以从 SageMaker AI 模型构件或配置好的 Hugging Face 仓库加载 GGUF 模型，然后通过 InvokeEndpoint 提供与 OpenAI 兼容的聊天补全，而无需自定义容器。当你的应用需要直接访问 logits 和模型状态操作时，你可以用 SemIf 适配器扩展该 DLC。对于对延迟不敏感的工作负载，选择 CPU；当提示词预填充和尾部延迟影响应用体验时，选择 GPU。

请查看代码示例、llama.cpp 的 AWS DLC 文档以及SageMaker AI 自定义推理容器契约，以便根据你的工作负载调整部署。

关于作者

Jyothirmai Kottu

Jyothirmai Kottu

Jyothirmai 是 AWS 深度学习容器团队的软件开发工程师。她构建 AI 和机器学习基础设施，专注于容器性能、可靠性和开发者易用性。工作之余，她喜欢咖啡、瑜伽，以及与家人和朋友一起探索新地方。

Daniel Wirjo

Daniel Wirjo

Daniel 是 AWS 的解决方案架构师，专注于前沿 AI 初创公司。作为曾经的初创公司 CTO，他喜欢与创始人和工程负责人合作，在 AWS 上推动增长和创新。工作之余，Daniel 喜欢手捧咖啡散步、欣赏自然，并学习新想法。

Daniel Quang

Daniel Quang

Daniel 是 AWS 前沿 AI 初创公司团队的解决方案架构师，帮助全球最大、最具战略意义的生成式 AI 初创公司在云上扩展其基础设施。他拥有加州大学欧文分校的计算机科学博士学位，研究方向为机器学习和生物信息学。

Dmitry Soldatkin

Dmitry Soldatkin

Dmitry 是 AWS 全球专家解决方案架构（SageMaker 推理）负责人。他帮助客户设计、构建和优化生成式 AI 与机器学习解决方案，兴趣涵盖深度学习和大规模部署机器学习。他热衷于持续创新，并利用数据推动业务成果。

来源：AWS Machine Learning Blog · aws.amazon.com

推理能力开源生态部署工程教程实践#教程/实践#部署/工程#推理#开源/仓库