コンテンツにスキップ

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 を保持して特定してください。

フィードバック

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