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를 보관하여 위치를 추적하십시오. |