genai-hub-orchestration

规则

1. 编排始终需要以正在运行的编排部署为前提条件——如果不存在，请先调用 aicore-lifecycle-management。
2. 编排端点为 POST {DEPLOYMENT_URL}/v2/completion，而不是 /v1/chat/completions。
3. 编排的 scenario_id 和 executable_id 始终为 "orchestration"——这是固定值。
4. Harmonized API 会将所有模型规范化为 OpenAI 消息格式——相同的客户端代码适用于 GPT、Gemini 和 Bedrock。
5. 如果尚未配置凭据，请先调用 aicore-admin-resources。
6. generative-ai-hub-sdk 已弃用——请始终使用 sap-ai-sdk-gen。两者共用导入命名空间 gen_ai_hub。
7. 如果用户的请求没有明确指定方式，请在编写或运行任何代码之前使用 AskUserQuestion 询问他们偏好 REST API（curl）还是 Python SDK。

---

部署前提条件

使用编排服务之前，必须有正在运行的部署：

# Check for an existing orchestration deployment:
uv run skills/aicore-lifecycle-management/scripts/get_deployments.py --scenario orchestration

# If none exists, create a configuration first (reuse if "orchestration" config already exists):
uv run skills/aicore-lifecycle-management/scripts/get_configurations.py --scenario-id orchestration --json | jq '.[] | select(.name == "orchestration")'
uv run skills/aicore-lifecycle-management/scripts/create_configuration.py \
  --name orchestration \
  --scenario-id orchestration \
  --executable-id orchestration

# Then deploy (takes up to 10 minutes):
uv run skills/aicore-lifecycle-management/scripts/create_deployment.py --configuration-id <config-id> --wait --timeout 600

---

工作流

步骤	操作	关键检查
1	确认编排部署处于 RUNNING 状态	get_deployments.py --scenario orchestration
2	如果未说明方式：通过 AskUserQuestion 询问选择 curl（REST API）还是 Python SDK	用户偏好
3	选择管道功能（仅模板化 / + 过滤 / + 内容 grounding）	用户意图
4	从 assets/ 中选择模板或从头构建	参见下方资源映射
5	运行并验证输出	uv run assets/<template>.py

---

资源映射

用例	模板
通过编排管道进行基础聊天	assets/orchestration_basic.py
带内容过滤的聊天（输入 + 输出）	assets/orchestration_filtering.py
使用文档 grounding 的 RAG	assets/rag_grounding.py

---

Python SDK — 关键模式

基础管道

from gen_ai_hub.orchestration.service import OrchestrationService
from gen_ai_hub.orchestration.models.config import OrchestrationConfig
from gen_ai_hub.orchestration.models.llm import LLM
from gen_ai_hub.orchestration.models.template import Template, TemplateValue
from gen_ai_hub.orchestration.models.message import SystemMessage, UserMessage

config = OrchestrationConfig(
    template=Template(messages=[
        SystemMessage("You are a helpful assistant."),
        UserMessage("{{?user_query}}"),
    ]),
    llm=LLM(name="gpt-4o-mini", version="latest"),
)
svc = OrchestrationService(config=config)
result = svc.run(template_values=[TemplateValue("user_query", "Hello")])
print(result.orchestration_result.choices[0].message.content)

添加内容过滤

from gen_ai_hub.orchestration.models.content_filtering import (
    ContentFiltering,
    InputFiltering,
    OutputFiltering,
)
from gen_ai_hub.orchestration.models.azure_content_filter import AzureContentFilter

filtering = ContentFiltering(
    input_filtering=InputFiltering(filters=[AzureContentFilter(hate=2, violence=2, sexual=2, self_harm=2)]),
    output_filtering=OutputFiltering(filters=[AzureContentFilter(hate=2, violence=2, sexual=2, self_harm=2)]),
)
config = OrchestrationConfig(template=..., llm=..., filtering=filtering)

---

REST API（curl）

export TOKEN=$(uv run skills/aicore-admin-resources/scripts/get_token.py)
export DEPLOYMENT_URL=$(uv run skills/aicore-lifecycle-management/scripts/get_deployments.py \
  --scenario orchestration --json 2>/dev/null | jq -r '.[0].deployment_url')
export RESOURCE_GROUP=$(uv run skills/aicore-admin-resources/scripts/check_setup.py 2>/dev/null | jq -r '.resource_group')

curl --request POST "${DEPLOYMENT_URL}/v2/completion" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "AI-Resource-Group: ${RESOURCE_GROUP}" \
  --header "content-type: application/json" \
  --data-raw '{
    "config": {
      "modules": {
        "prompt_templating": {
          "prompt": {
            "template": [
              {"role": "system", "content": "You are a helpful assistant."},
              {"role": "user",   "content": "{{?user_query}}"}
            ]
          },
          "model": {
            "name": "gpt-4o-mini",
            "params": {"max_completion_tokens": 512}
          }
        }
      }
    },
    "placeholder_values": {"user_query": "What is SAP AI Core?"},
    "messages_history": []
  }'

使用以下命令提取答案：jq '.final_result.choices[0].message.content'

推理模型（Gemini 2.5 Pro、o3）：将 max_completion_tokens 设为至少 1024——推理令牌会在可见回复生成前消耗预算。

---

转交

• 没有正在运行的编排部署？ → 调用 aicore-lifecycle-management
• 凭据/身份验证错误？ → 调用 aicore-admin-resources
• 需要查找模型名称？ → 调用 genai-hub-foundation-models
• 需要完整的 Java SDK 样板代码（非编排）？ → 调用 aicore-sdk-java
• 需要完整的 JS SDK 样板代码（非编排）？ → 调用 aicore-sdk-js

---

何时加载参考文件

触发条件	加载
REST API 详情、请求/响应结构、Harmonized API	references/ORCHESTRATION.md
文档 grounding 设置、GroundingModule 配置、RAG	references/GROUNDING.md