コンテンツにスキップ

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 製品専用の入口を使用し、本インターフェース経由で組み込みアプリケーションを変更しないでください。

フィードバック

このページは役に立ちましたか?