LLM 設定の変更¶
POST /api/v1/llm_cfg/{appid}/modify
概要¶
LLM アプリケーション設定、公開識別子、または Token の関連付けを変更します。
呼び出し前の準備と使用手順¶
現在の Key には llm.llmCfgManage が必要で、現在のワークスペースのみが対象です。作成時は jsonContent.name/type が必須で、appId は省略すると自動生成されます。実際にはハイフンも許可されます。appType は渡せません。専用 Agent モニタリングの組み込みアプリケーションはこのグループで保護されており、extend/予約名に依存して専用フローを回避することはできません。
jsonContent はフィールド単位でマージされ、extend が指定された場合はオブジェクト全体を置き換え、{} はクリアします。変更不要なフィールドは省略します。newAppId が空でない場合は名前変更となり、外部参照も同期する必要があります。clientToken を省略/空にした場合は保持され、レスポンスの clientToken は内部の wctn_ UUID となるため SDK に設定できません。平文が必要な場合は詳細を取得してください。バインディングを変更しても古い Token は失効しないため、アプリケーション関連付けの変更を資格情報の失効として扱わないでください。{} でも更新時刻は更新され、下流への通知がトリガーされます。
データベースのコミット後、アプリケーションのデータベース ID に基づいて下流へ同期的に更新通知を行います。失敗した場合でも設定/Token が保存済みの可能性があるため、まず簡易一覧/詳細で現在の状態を確認してから再試行してください。下流への通知成功は、収集や rollup がすでに反映されたことを意味しません。site は保存されたアドレスにすぎず、HTTP 成功はサードパーティ Langfuse の認証成功を意味しません。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| appid | string | Y | 現在の Key のワークスペースの公開 appId。内部の実際の LlmCfg UUID ではありません。パスはそのまま URL エンコードされます。 例: payment_llm取得または入力方法: LLM アプリケーション簡易一覧 から content[].appId(uuid は同じ公開エイリアス)を取得するか、ページネーションリストの content.data[].appId を使用します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| jsonContent.extend.カスタムキー | any | 任意の JSON 値で、オブジェクト/配列/文字列/数値/ブール値/null を使用できます。LLM サービスの資格情報や実行設定として扱うことは保証されません。 例: payment取得または入力方法: 呼び出し元が拡張情報を表示するために使用します。 |
|
| clientToken | string | 作成時に省略/空の場合はランダムな16進数が自動生成されます。明示的な値を指定すると、グローバルで未削除の同一値レコードの再利用が試行されますが、現在は RUM の同一ワークスペース/ステータス 2 による拒否検証はありません。変更時に明示的な値を指定すると、削除済みの同一値レコードを再利用する可能性さえあり、他ワークスペース/削除済みの値をサーバー側が拒否することに依存できません。呼び出し元は、現在のワークスペースで有効であることを確認済みの値のみを使用するか、作成時に省略してください。エンティティの最大長は 64 文字です。変更時に省略/空の場合は関連付けが保持されますが、レスポンスでは平文ではなく内部の wctn_ UUID が返されます。明示的に空でない場合にのみ、渡した平文が返されます。 空文字列を許可: True null を許可: False 例: <LLM-CLIENT-TOKEN>取得または入力方法: 作成時は省略して自動生成することを推奨します。再利用する場合は、事前に対象ワークスペースで有効な Client Token の平文を確認する必要があります。 |
|
| jsonContent | json | 作成時は必須のオブジェクトで、変更時は省略可能で {} として扱われます。宣言できるキーは name/type/site/extend のみです。変更時はこれらのキーで既存オブジェクトをマージし、extend が指定された場合はオブジェクト全体を置き換え、再帰的にはマージしません。 例: {"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 | 作成時は必須の文字列で、最大 256 文字です。空でないことは強制されませんが、空でないことを推奨します。変更時に省略した場合は保持されます。有効な同名が存在する場合は 400 になります。統計は appId ではなく名前で照合されるため、名前変更後は一時的に統計が存在しない可能性があります。 null を許可: False 最大長: 256 例: 支付助手取得または入力方法: 呼び出し元が現在のワークスペースで一意のアプリケーション表示名を入力し、収集時の app_name と一致させます。 |
|
| jsonContent.site | string | オプションの文字列です。作成時に省略した場合は補完されず、変更時に省略した場合は保持されます。アドレスの保存によってサードパーティプロジェクトの作成/認証/ヘルスプローブはトリガーされません。 null を許可: False 例: https://llm.example.com取得または入力方法: 顧客が実際にアクセスできる LLM プラットフォームのアドレスを入力します。API Key/資格情報は入力しないでください。 |
|
| jsonContent.type | string | 作成時は必須、変更時は省略可能です。公開されている唯一の列挙値は Langfuse です。変更時はこのフィールドの更新が許可され、RUM の型変更禁止ルールは適用されません。 null を許可: False 選択可能な値: ['Langfuse'] 例: Langfuse取得または入力方法: 現在公開されている固定の選択肢は Langfuse です。 |
|
| newAppId | string | オプションで最大 128 文字、ASCII の英数字、アンダースコア、ハイフンを使用できます。省略/空の場合は保持されます。変更後は収集時の app_id などの参照を同期する必要があり、内部の実際の UUID は変わりません。古い appId は位置特定に使用されなくなります。 空文字列を許可: True null を許可: False $maxCharacterLength: 128 例: payment_llm_v2取得または入力方法: SDK 移行計画に従って新しい公開識別子を決定し、事前に使用済みかどうかを確認します。 |
パラメータ補足説明¶
appId は公開アプリケーション識別子で、uuid はその互換エイリアスです。本ページの実際の Token、統計、エラーの境界に従って使用し、フロントエンド/AI インターフェースの追加パラメータをそのまま流用しないでください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/llm_cfg/payment_llm/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"jsonContent":{"name":"支付助手"}}'
レスポンス¶
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": 7,
"uuid": "payment_llm",
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427260,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"appId": "payment_llm",
"appType": "",
"jsonContent": {
"name": "支付助手",
"type": "Langfuse",
"site": "https://llm.example.com",
"extend": {
"team": "payment"
}
},
"clientToken": "wctn_example",
"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 を保持して特定してください。 |
| 404 | ft.InvalidLlmAppuuid | 現在のワークスペースに対象アプリケーションが存在しない/削除済みです | LLM アプリケーションが存在しません | 簡易一覧から appId を再取得してください。 |
| 400 | ft.InvalidAction | 対象が保護された Agent モニタリングの組み込みアプリケーションです | Agent monitor builtin applications cannot be modified or deleted | 製品専用の入口を使用し、本インターフェース経由で組み込みアプリケーションを変更しないでください。 |