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	パイプラインの機能を選択します（テンプレート化のみ／＋フィルタリング／＋グラウンディング）	ユーザーの意図
4	assets/ からテンプレートを選択するか、スクラッチから作成します	下記のアセットマップを参照
5	実行して出力を検証します	uv run assets/<template>.py

---

アセットマップ

ユースケース	テンプレート
オーケストレーションパイプラインによる基本的なチャット	assets/orchestration_basic.py
コンテンツフィルタリング付きチャット（入力＋出力）	assets/orchestration_filtering.py
ドキュメントグラウンディングを使用する 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
ドキュメントグラウンディングの設定、GroundingModule の構成、RAG	references/GROUNDING.md