콘텐츠로 이동

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

문서 평가

이 페이지가 도움이 되었나요?