LLM 設定を追加¶
POST /api/v1/llm_cfg/add
概要¶
LLM アプリケーションを作成し、クライアント Token の関連付けを確立します。
呼び出し前の準備と使用手順¶
現在の Key には llm.llmCfgManage 権限が必要で、現在のワークスペースにのみ適用されます。作成時は jsonContent.name/type が必須で、appId を省略すると自動生成されます。実際にはハイフンも使用できます。appType は送信できません。専用 Agent モニタリングの組み込みアプリケーションはこのグループで保護されているため、extend や予約名に依存して専用フローを回避することはできません。
作成には冪等キーがなく、有効な名前/appId が競合すると 400 になります。明示的な Client Token は現在のワークスペースで有効な平文のみを使用してください。現在の再利用ロジックには同一ワークスペース/すべてのステータスに対する信頼できる検証がないため、サーバー側での自動生成を推奨します。成功レスポンスは権限を持つ収集側が接続するための平文を返し、DF-API-KEY は送信しません。
データベースのコミット後、アプリケーションのデータベース ID に従って下流へ同期的に更新通知を行います。失敗した場合でも設定/Token が保存済みである可能性があるため、まず一覧/詳細で現在の状態を確認してから再試行してください。下流への通知成功は、収集や rollup が既に発生したことを意味しません。site は保存されたアドレスにすぎず、HTTP の成功はサードパーティ Langfuse の認証成功を意味しません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| jsonContent.extend.カスタムキー | any | 任意の JSON 値で、オブジェクト/配列/文字列/数値/ブール/null を指定できます。LLM サービスの認証情報や実行設定として扱われることを保証しません。 例: payment取得または入力方法: 呼び出し側が拡張情報を表示します。 |
|
| appId | string | 作成時は省略可能で、省略または空の場合は llmcfg_ プレフィックスの公開値を自動生成します。最大 128 文字で、実際の正規表現は ASCII 英字/数字/アンダースコア/ハイフンのみです。ハイフンは使用可能で、旧記述では漏れていました。システムの agent_monitor_builtin_ 予約識別子は使用しないでください。 空文字列の許可: True null の許可: False $maxCharacterLength: 128 例: payment_llm取得または入力方法: 呼び出し側が SDK/収集設定向けに、ワークスペース内で一意な公開識別子を约定します。 |
|
| clientToken | string | 作成時は省略または空の場合、ランダムな 16 進数を自動生成します。明示的な値はグローバルで未削除の同一値レコードの再利用を試みますが、現在 RUM の同一ワークスペース/ステータス 2 の拒否検証はありません。明示値を変更すると削除済みの同一値レコードを再利用する可能性があり、サーバーが他のワークスペースや削除済みの値を拒否することに依存できません。呼び出し側は、現在のワークスペースで有効であることを確認済みの値のみを使用するか、作成時に省略してください。エンティティは最大 64 文字です。変更時に省略または空の場合は関連付けを保持しますが、レスポンスは平文ではなく内部の wctn_ UUID を返します。明示的に非空の場合のみ、渡した平文を返します。 空文字列の許可: True null の許可: False 例: <LLM-CLIENT-TOKEN>取得または入力方法: 作成時は省略して自動生成することを推奨します。再利用する場合は、事前に対象ワークスペースで有効な Client Token の平文を確認してください。 |
|
| jsonContent | json | Y | 作成時は必須のオブジェクト、変更時は省略可能で {} として扱います。name/type/site/extend の宣言キーのみ許可します。変更時はこれらのキーで旧オブジェクトをマージし、extend が存在する場合はオブジェクト全体を置換し、再帰的なマージは行いません。 null の許可: False 例: {"name": "支付助手", "type": "Langfuse", "site": "https://llm.example.com", "extend": {"team": "payment"}}取得または入力方法: LLM アプリケーションの接続製品と表示名に従って構築します。 |
| jsonContent.extend | json | 省略可能な JSON オブジェクトで、null/配列/文字列は事前に拒否されます。省略時は保持し(作成時は補完しない)、{} でクリアし、存在する場合は全体を置換します。公開された固定の実行サブキーはなく、extend.builtin に依存して専用の組み込みアプリケーションを作成することはできません。 null の許可: False 例: {"team": "payment"}取得または入力方法: 呼び出し側がアプリケーションの表示情報を保存します。変更前に保持が必要な完全なオブジェクトをコピーしてください。 |
|
| jsonContent.name | string | Y | 作成時は必須の文字列で最大 256 文字、非空は強制されませんが非空を推奨します。変更時に省略した場合は保持します。有効な同名は 400 になります。統計は appId ではなく名前でマッチングするため、改名すると一時的に統計がなくなる場合があります。 null の許可: False 最大長: 256 例: 支付助手取得または入力方法: 呼び出し側が現在のワークスペースで一意なアプリケーション表示名を入力し、収集側の app_name と一致させます。 |
| jsonContent.site | string | 省略可能な文字列で、作成時に省略した場合は補完せず、変更時に省略した場合は保持します。アドレスを保存してもサードパーティプロジェクトの作成/認証/ヘルスチェックはトリガーされません。 null の許可: False 例: https://llm.example.com取得または入力方法: 顧客が実際にアクセスできる LLM プラットフォームのアドレスを入力してください。API Key/認証情報は入力しないでください。 |
|
| jsonContent.type | string | Y | 作成時は必須、変更時は省略可能で、唯一の公開列挙値は Langfuse です。変更時にこのフィールドの更新を許可し、RUM の型変更禁止ルールを踏襲しません。 null の許可: False 選択可能な値: ['Langfuse'] 例: Langfuse取得または入力方法: 現在の公開された固定選択肢は Langfuse です。 |
パラメータ補足説明¶
appId は公開アプリケーション識別子、uuid はその互換エイリアスです。本ページの実際の Token、統計、エラー境界に従って使用し、フロントエンド/AI インターフェースの追加パラメータをそのまま流用しないでください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/llm_cfg/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"appId":"payment_llm","jsonContent":{"name":"支付助手","type":"Langfuse","site":"https://llm.example.com","extend":{"team":"payment"}}}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 保存されたアプリケーションスナップショット。統計/ifTokenExpired は付与されません。 |
| content.id | integer または null | データベース行 ID。パスによる特定には使用しません。コミット前のスナップショットでは null になる場合があります。 |
| content.uuid | string | 公開互換エイリアスで appId と等しく、内部の実際の LlmCfg UUID ではありません。 |
| content.status | integer | リソースステータス。通常は 0 で、論理削除の 3 はクエリから除外されます。 |
| content.creator | string | 作成主体の UUID。現在の OpenAPI では通常 Key リソースの wsak_ です。 |
| content.updator | string | 最近の更新主体。未更新の場合は空になることがあります。 |
| content.createAt | integer | Unix 秒の作成時刻。 |
| content.updateAt | integer | Unix 秒の更新時刻。未更新の場合は通常 -1 です。 |
| content.deleteAt | integer | Unix 秒の削除時刻。未削除の場合は通常 -1 です。 |
| content.workspaceUUID | string | 現在の Key が属するワークスペース。 |
| content.appId | string | 公開アプリケーション ID。既定では llmcfg_ プレフィックスの値が自動生成されます。 |
| content.appType | string | アプリケーション族のマーカー。公開作成では通常空で、履歴には llm/agent/obsyTeam などがあり得ます。この公開入力では appType を許可しません。 |
| content.jsonContent | object | アプリケーションの表示/接続設定。宣言されていない追加のトップレベルサブキーを含めて書き込むことはできません。 |
| content.jsonContent.name | string | アプリケーションの表示名。統計はこの名前でマッチングします。 |
| content.jsonContent.type | string | 公開書き込みは Langfuse のみです。履歴の型は異なる場合がありますが、公開して書き戻せることを意味しません。 |
| content.jsonContent.site | string | 省略可能な保存済みサイトアドレス。サーバーがこのフィールドによってサードパーティプロジェクトを自動作成したり、接続可否を検証したりすることはありません。 |
| content.jsonContent.extend | object | 省略可能な動的拡張オブジェクト。指定しない場合はキーを省略できます。 |
| content.jsonContent.extend.カスタムキー | JSON | そのまま保存される JSON 値。追加の実行/認証設定を保証しません。 |
| content.clientToken | string | 一覧/詳細/作成では Client Token の平文です。変更時にパラメータを省略または空にした場合は内部の wctn_ UUID を返す互換分岐があります。詳細は該当ページを参照してください。 |
| content.declaration | object または null | 現在のワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "payment_llm",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"appId": "payment_llm",
"appType": "",
"jsonContent": {
"name": "支付助手",
"type": "Langfuse",
"site": "https://llm.example.com",
"extend": {
"team": "payment"
}
},
"clientToken": "<LLM-CLIENT-TOKEN>",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
本体のデータベースは先にコミットされ、その後、設定変更通知が同期的に呼び出されます。下流の業務 4xx は実際の HTTP/errorCode/message で返される場合があり、透過されない >=500 は一律 500 になります。後続のいかなるエラーもデータベースのロールバックを保証しないため、まず読み戻して確認してください。統計クエリの異常は通常、すべて null としてフォールトトレラントされ、書き込み通知のエラーと混同されません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータの解析に失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトでない | 一部の json ファイルの形式エラー | jsonContent オブジェクトを送信してください。 |
| 400 | ft.InvalidLlmAppId | 空でない appId/newAppId に正規表現でサポートされない文字が含まれる | LLM アプリケーションの appId には英字、数字、アンダースコア、ハイフンのみ使用できます | ASCII 英数字、アンダースコア、ハイフンのみを使用し、最大 128 文字にしてください。 |
| 400 | ft.SignNameRepeat | 現在のワークスペースに有効な同一 appId が既に存在 | 現在のワークスペースには同名の識別子 payment_llm が既に存在します |
まず一覧/詳細を確認し、未使用の識別子を使用してください。 |
| 400 | ft.LlmCfgNameRepeat | 現在のワークスペースに有効な同一 jsonContent.name が既に存在 | 現在のワークスペースには同名の LLM 設定名 支付助手 が既に存在します |
独立した名前を選択するか、元のアプリケーションを特定して変更してください。 |
| 500 | ft.InternalServerError | データベース/Token/履歴設定、コミット後の設定通知の下流呼び出し、またはレスポンス構築の異常 | 内部エラー | まず appId/名前/Token のバインドと下流の実際の接続を読み戻して確認してください。本体は既にコミットされている可能性があるため、むやみに再作成したり Token を変更したりしないでください。traceId を保持して特定してください。 |