使用 SAP Cloud SDK for AI 与编排服务交互

学习目标

  • 使用 SAP Cloud SDK for AI 与 Orchestration 服务交互。

诸如 SAP Cloud SDK for AI (Python) 之类的 SDK 让您能够轻松地将应用程序连接到生成式 AI 功能。

现在，我们将把这一知识向前推进一步，演示如何使用这个强大的 SDK 以编程方式访问和控制 Orchestration Service。

本课将引导您完成使用 SAP Cloud SDK for AI 定义完整编排工作流的过程。您将了解如何以编程方式设置模板、定义 LLM 参数，并执行利用接地、过滤和屏蔽等能力的复杂多步 AI 任务，所有这些都通过精简的 SDK 接口完成。

Orchestration Service 交互

要以编程方式与 Orchestration Service 交互，通常需要遵循以下高层步骤：

  • 身份验证： 获取身份验证令牌（Bearer 令牌）。

  • 部署： 为 Orchestration Service 创建部署并获取您唯一的 ORCH_DEPLOYMENT_URL。

  • 消费： 以编程方式向已部署的 Orchestration Service 端点发送请求。这是本课的主要重点。

适用于 Python 的 SAP Cloud SDK for AI 提供了一种稳健而直观的方式，可直接从您的 Python 应用程序中定义、配置和执行 Orchestration Service 工作流。这使您能够轻松地将复杂的生成式 AI 能力集成到业务逻辑中。

在继续之前，请确保您已完成前面讨论的 Python SDK 安装和配置步骤，包括设置 ~/.aicore/config.json 文件。

使用 Orchestration Service

执行以下步骤以使用 Orchestration 服务：

  1. 获取 Orchestration 的身份验证令牌

  2. 为 Orchestration 创建部署

  3. 消费 Orchestration

要使用 SDK 与 Orchestration Service 交互，请遵循以下流程步骤：

  1. 初始化 Orchestration Service 客户端

  2. 定义编排模板

  3. 定义 LLM

  4. 创建编排配置

  5. 运行编排请求

第 1 步：初始化 Orchestration Service 客户端

首先，您需要导入必要的类，并将 SDK 客户端指向您在部署 Orchestration Service 时获得的 ORCH_DEPLOYMENT_URL。

# Assuming YOUR_API_URL is the ORCH_DEPLOYMENT_URL.
YOUR_API_URL = "https://your-orchestration-deployment-url.ai.sap.com/orchestration-service-endpoint"
from gen_ai_hub.orchestration.service import OrchestrationService

Note

将 your-orchestration-deployment-url 替换为您实际的 Orchestration Deployment URL。

第 2 步：定义编排模板

SDK 中的 Template 对象允许您以编程方式定义提示的结构，包括系统、用户和助手消息。它还允许您为动态输入定义占位符并设置默认值。

让我们考虑一个翻译助手的示例。

from gen_ai_hub.orchestration.models.message import SystemMessage, UserMessage
from gen_ai_hub.orchestration.models.template import Template, TemplateValue

template = Template(
messages=[
SystemMessage("You are a helpful translation assistant."),
UserMessage(
"Translate the following text to {{?to_lang}}: {{?text}}"
),
],
defaults=[
TemplateValue(name="to_lang", value="German"),
],
)

这段 Python 代码为翻译助手设置了一个模板。它定义了一个 SystemMessage 来确立助手的角色，以及一个包含占位符（{{?to_lang}} 和 {{?text}}）的 UserMessage，用于目标语言和要翻译的文本。它还将默认目标语言设置为 "German"，使该模板可以立即用于将文本翻译为德语，而无需每次显式指定语言。

第 3 步：定义 LLM

接下来，您定义 Orchestration Service 应使用哪个 LLM 来进行 prompt_templating 模块。这涉及指定模型的名称、版本以及任何特定参数（例如 max_tokens 或 temperature）以控制其行为。

from gen_ai_hub.orchestration.models.llm import LLM

llm = LLM(name="gpt-4o", version="latest", parameters={"max_tokens": 256, "temperature": 0.2})

这段代码创建了一个 LLM 实例，例如这里是 "gpt-4o"。它将编排服务配置为使用生成式 AI 中心中可用的最新版本。

它还设置了诸如响应最大令牌限制为 256 以及温度为 0.2 之类的参数，以控制响应变化程度（温度越低意味着输出越确定）。此设置为您编排的任务定义了生成式 AI 引擎。

第 4 步：创建编排配置

OrchestrationConfig 对象将您定义的模板和 LLM（以及可选的接地、过滤、屏蔽、翻译等其他模块）组合为工作流的单一可执行配置。

from gen_ai_hub.orchestration.models.config import OrchestrationConfig

config = OrchestrationConfig(
template=template,
llm=llm,
)

这段代码使用前几步中定义的 template 和 llm 变量初始化了一个 OrchestrationConfig 实例。此配置对象封装了您特定编排 AI 工作流的整体设计，确保系统在执行时使用指定的模板和语言模型参数。

第 5 步：运行编排请求

最后，您通过调用 OrchestrationService 客户端的 run 方法来执行已定义的编排工作流。您需要传入模板占位符所需的任何动态 template_values。

# Instantiate the OrchestrationService with your API URL and defined config
orchestration_service = OrchestrationService(api_url=YOUR_API_URL, config=config)

# Run the orchestration, providing values for the template placeholders
result = orchestration_service.run(template_values=[
TemplateValue(name="text", value="The Orchestration Service is working!")
])

# Print the content of the LLM's response
print(result.orchestration_result.choices[0].message.content)

这段代码首先使用您部署的端点 URL 和已配置的工作流初始化 OrchestrationService 客户端。然后它通过调用 run() 执行编排任务，为模板中的 {{?text}} 占位符提供文本 "The Orchestration Service is working!"。随后打印结果内容（基于模板默认值翻译为德语后的文本），演示了与 Orchestration Service 的成功编程交互。

使用其他模块扩展编排配置

上述示例演示了使用 prompt_templating 和 LLM 的简单翻译。然而，Orchestration Service 的真正强大之处在于它能够链接多个模块。您可以进一步扩展 OrchestrationConfig 以包含：

  • grounding ：从您的企业来源注入实时的事实数据。

  • filtering ：用于输入和输出内容安全检查。

  • masking ：用于保护 PII 等敏感数据。

  • translation ：用于处理多语言输入和输出。

您可以使用模块进行内容过滤和其他任务。Obtain Optional Modules for details and the latest orchestration configurations.

本课小结

您已成功学习如何使用 SAP Cloud SDK for AI (Python) 以编程方式与 Orchestration Service 交互。您已经完成了初始化服务客户端、定义提示模板和 LLM 参数、创建完整的编排配置以及执行工作流的各个步骤。这种编程控制对于将高级生成式 AI 能力无缝集成到企业应用程序中至关重要，使您能够构建可扩展、自动化且功能丰富的解决方案，充分利用 SAP 生成式 AI 中心的全部能力。