スキルOfficialdevelopment

🗄️aidp-ai-sql

プラグイン: oracle-ai-data-platform-workbench-engineer-agent
ソース: GitHub で見る ↗

説明

Spark SQL内で`ai_generate()`を使用してAIDP上のLLM関数を実行します。次のような場合に使用: - SQLの中で直接LLMを使って行の要約・分類・抽出・エンリッチメントを行いたい場合 - 集計結果に基づいてナラティブ（説明文）を生成したい場合 - レイクハウス上でRAGスタイルのグラウンデッド分析を行いたい場合シグネチャはモデルを第一引数に取る形式で、利用可能なモデルは実際に使用する前に都度確認が必要です。

原文を表示

Run LLM functions inside Spark SQL on AIDP via ai_generate(). Use when the user wants to summarize/classify/extract/enrich rows with an LLM directly in SQL, generate narratives over aggregated results, or do grounded RAG-style analysis in the lakehouse. Signature is model-first; available models must be confirmed live before relying on it.

ユースケース

✓SQLで行の要約・分類・抽出を行いたい
✓集計結果からナラティブを生成したい
✓レイクハウス上でRAG分析を実行したい

本文（日本語訳）

`aidp-ai-sql` — `ai_generate()` を使った LLM-in-SQL

AIDP 上の Spark SQL 内から直接 LLM を呼び出し、SQL を離れることなくレイクハウスデータに対して要約・分類・抽出・ナレーション生成を行います。競合の多くの agent がインライン実行できないこの機能は、際立った差別化ポイントです。

これは SQL-helper スキルです。インタラクティブな Spark SQL は、バンドルされたヘルパースクリプト scripts/aidp_sql.py 経由で実行されます（api_key の DEFAULT プロファイルから UPST を生成し、スクラッチノートブックを自動作成して JSON を返します）。 aidp MCP および AIDP_SESSION は不要です。

次のような場合に使用

「SQL の中で AI を使ってこれらの行を要約 / 分類 / 抽出 / エンリッチしたい。」
集計結果をもとに根拠のあるナレーションを生成したい（例: 支出ロールアップに対する財務サマリーなど）。

シグネチャ（model を最初に指定）

ai_generate('<model>', '<prompt>')

例: ai_generate('openai.gpt-5.4', 'Summarize this supplier spend: ...')

openai.gpt-5.4・openai.gpt-4o・xai.grok-4 にて、model を先頭に置く (model, prompt) シグネチャを 実環境で検証済み。

利用前に必ず確認してください（情報の捏造禁止）: このシグネチャおよび利用可能なモデル名を保証されたものとして扱う前に、対象クラスター上で実際に動作確認してください。まず SELECT ai_generate('<model>', 'hello') のような簡単なスモークテストを実行してください（下記参照）。モデルの利用可否は環境によって異なります。モデル名が失敗した場合は、正しいモデル名を確認・質問してください。推測で補わないこと。

/models REST カタログで可否を判断しないでください。 ai_generate はモデルを Spark エンジンレベルで解決するため、aidp-models-catalog の GET /models?modelType=GENERATIVE_AI が空リストを返す場合でも動作することがあります。 ai_generate が使えるかどうかの判断基準は、カタログエンドポイントではなくスモークテストです。

セルの実行方法

python "$PLUGIN_DIR/scripts/aidp_sql.py" \
  --region <region> --datalake <DATALAKE_OCID> --workspace <ws> --cluster <cluster-key> \
  --code "<python/spark code>"

返却値は JSON 形式: {"status":"ok|error","outputs":[...],"spark_job_ids":[...]} 成功時は exit 0、セルエラー時は exit 1。完全なフラグ一覧（--profile・--session-profile・--notebook・--timeout）は scripts/aidp_sql.py を参照。

スモークテスト（最初に実行してください）

python "$PLUGIN_DIR/scripts/aidp_sql.py" --region <region> --datalake <ocid> --workspace <ws> --cluster <key> \
  --code "spark.sql(\"SELECT ai_generate('openai.gpt-5.4', 'hello')\").show(truncate=False)"

ワークフロー（グラウンデッド RAG パターン）

クラスターが RUNNING 状態であることを確認（oci raw-request 経由のクラスター操作については references/no-mcp-rest-map.md を参照）。
まずグラウンディング: LLM に推論させたい行を事前に集計・選択しておく（小さく、関連性の高いセットに絞る）。
そのグラウンデッドなコンテキストをプロンプトに埋め込み、ai_generate('<model>', '<grounded prompt>') を呼び出す。行単位のエンリッチメントには、行数を制限した上でカラム式として呼び出す。
生成されたテキストとその元データをユーザーが検証できるよう、並べて提示する。

--code にセルを渡す例:

ctx = spark.sql("SELECT ... FROM gold.supplier_spend ...").toPandas().to_string()
res = spark.sql(f"SELECT ai_generate('openai.gpt-5.4', 'As a finance analyst, summarize: {ctx}') AS summary")
res.show(truncate=False)

信頼性に関するルール

プロンプトは必ず実際のクエリ結果に基づいてグラウンディングすること。モデルが参照できないデータを想起させないこと。
行単位の ai_generate はコストとレイテンシを考慮し、処理行数を制限すること。
AI が生成したナレーションには必ず裏付けとなるデータを提示すること。SQL なしで生成された数値を事実として提示しないこと。

参考資料

scripts/aidp_sql.py — SQL / ノートブックセル実行ヘルパー（バンドル済み）
references/oci-raw-request.md — REST コントロールプレーン（クラスター管理・認証）
references/no-mcp-rest-map.md — aidp-analyzing-data と組み合わせて使用

原文（English）を表示

`aidp-ai-sql` — LLM-in-SQL with `ai_generate()`

Call an LLM directly inside Spark SQL on AIDP — summarize, classify, extract, or narrate over lakehouse data without leaving SQL. A signature differentiator: most competitor agents can't do this inline.

This is a SQL-helper skill. Interactive Spark SQL runs through the bundled helper scripts/aidp_sql.py (it mints a UPST from the api_key DEFAULT profile, auto-creates a scratch notebook, and returns JSON). No aidp MCP and no AIDP_SESSION required.

When to use

"Summarize / classify / extract / enrich these rows with AI in SQL."
Generate a grounded narrative over an aggregate (e.g. a finance summary over a spend rollup).

Signature (model FIRST)

ai_generate('<model>', '<prompt>')

e.g. ai_generate('openai.gpt-5.4', 'Summarize this supplier spend: ...').

LIVE-VERIFIED model-first (model, prompt) signature with openai.gpt-5.4, openai.gpt-4o, and xai.grok-4.

Verify before relying on it (no-fabrication): confirm the exact signature and the available model names live on the target cluster before treating this as guaranteed — run a trivial SELECT ai_generate('<model>', 'hello') cell first (see smoke test below). Model availability varies by environment. If a model name fails, list/ask for the correct one rather than guessing.

Don't gate on the /models REST catalog. ai_generate resolves the model at the Spark engine level, so it can work even when aidp-models-catalog's GET /models?modelType=GENERATIVE_AI returns an empty list. The smoke test (not the catalog endpoint) is the source of truth for whether ai_generate works.

How to run a cell

python "$PLUGIN_DIR/scripts/aidp_sql.py" \
  --region <region> --datalake <DATALAKE_OCID> --workspace <ws> --cluster <cluster-key> \
  --code "<python/spark code>"

Returns JSON: {"status":"ok|error","outputs":[...],"spark_job_ids":[...]}. Exit 0 on success, 1 on cell error. See scripts/aidp_sql.py for full flags (--profile, --session-profile, --notebook, --timeout).

Smoke test (do this first)

python "$PLUGIN_DIR/scripts/aidp_sql.py" --region <region> --datalake <ocid> --workspace <ws> --cluster <key> \
  --code "spark.sql(\"SELECT ai_generate('openai.gpt-5.4', 'hello')\").show(truncate=False)"

Workflow (grounded RAG pattern)

Ensure cluster RUNNING (cluster-ops via oci raw-request; see references/no-mcp-rest-map.md).
Ground first: aggregate/select the rows you want the LLM to reason over (small, relevant set).
Embed that grounded context into the prompt and call ai_generate('<model>', '<grounded prompt>'). For per-row enrichment, call it as a column expression over a bounded set.
Present the generated text alongside the underlying data so the user can verify it.

Pass the cell to --code:

ctx = spark.sql("SELECT ... FROM gold.supplier_spend ...").toPandas().to_string()
res = spark.sql(f"SELECT ai_generate('openai.gpt-5.4', 'As a finance analyst, summarize: {ctx}') AS summary")
res.show(truncate=False)

Reliability rules

Always ground the prompt in real query output — don't ask the model to recall data it can't see.
Bound row counts for per-row ai_generate (cost + latency).
Show the data behind any AI narrative; never present generated numbers as ground truth without the SQL.

References

scripts/aidp_sql.py — the SQL/notebook-cell executor (bundled helper)
references/oci-raw-request.md — REST control-plane (clusters, auth)
references/no-mcp-rest-map.md · pairs with aidp-analyzing-data

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。