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를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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 | 제품 전용 진입점을 사용하고, 이 인터페이스로 내장 애플리케이션을 수정하지 마세요. |