KO ▾
API 키 받기
개발자를 위한 OpenAI 호환 무검열 API. 업데이트

Uncensored LLM API JSON 모드 및 도구 호출

무검열 LLM API의 JSON 모드 전환은 OpenAI 클라이언트에서 이미 알고 있는 것과 동일합니다: response_format에 type json_object를 보내면 응답이 JSON 객체로 돌아옵니다. 이 페이지에서는 해당 기능과 함께 코드에서 직접 실행할 수 있는 도구 호출 방법을 다룹니다.

큐브로 조립된 빛나는 괄호들이 기계식 팔에 의해 조립되며, 구조화된 JSON 출력과 도구 호출을 보여줍니다.

curl로 시작하기

가장 작은 작동 JSON 모드 요청은 다음과 같습니다. Base URL https://api.uncensoredllmapi.com/v1, 모델 uncensored 및 Bearer 토큰으로 키를 사용합니다:

curl https://api.uncensoredllmapi.com/v1/chat/completions   -H "Authorization: Bearer $UNCENSORED_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "uncensored",
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "Reply only with a JSON object."},
      {"role": "user", "content": "Create a tavern NPC with keys name, trade and rumour."}
    ]
  }'

choices[0].message.content의 어시스턴트 메시지는 JSON 객체를 포함하는 문자열입니다. 직접 구문 분석해야 합니다. 프롬프트의 지시를 생략하지 마세요. JSON 모드는 출력을 객체로 제한하지만 원하는 키를 추측할 수는 없습니다. 키를 명시하고 이상적으로는 한 줄 예시를 보여주는 것이 안정적인 구조를 제공합니다.

아직 키가 없다면, API 키 페이지에서 로그인 후 한 번의 클릭으로 $0.50의 무료 체험 크레딧을 제공합니다. 이 크레딧에는 결제가 필요 없으며, 7일 동안 유효하고 사람당 하나만 제한됩니다.

Python에서 검증과 함께 JSON 모드

모델 출력을 다른 외부 입력처럼 취급하세요. 구문 분석하고 스키마로 확인한 후, 실패 시 제한된 횟수만큼 재시도하세요. Pydantic을 사용하면 다음과 같이 간단하게 처리할 수 있습니다:

import json, os
from openai import OpenAI
from pydantic import BaseModel, ValidationError

client = OpenAI(
    base_url="https://api.uncensoredllmapi.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
)

class Npc(BaseModel):
    name: str
    trade: str
    rumour: str

SYSTEM = (
    "Reply only with a JSON object with exactly these keys: "
    "name, trade, rumour. Each value is a string."
)

def make_npc(setting, tries=3):
    for _ in range(tries):
        r = client.chat.completions.create(
            model="uncensored",
            response_format={"type": "json_object"},
            messages=[
                {"role": "system", "content": SYSTEM},
                {"role": "user", "content": f"Setting: {setting}"},
            ],
            temperature=0.7,
            max_tokens=300,
        )
        choice = r.choices[0]
        if choice.finish_reason == "length":
            continue           # cut off, so the JSON is incomplete
        try:
            return Npc(**json.loads(choice.message.content))
        except (json.JSONDecodeError, ValidationError, TypeError):
            continue
    raise RuntimeError("no valid JSON after retries")

print(make_npc("a river port in a plague year"))

이 코드에는 세 가지 모방할 습관이 있습니다. 코드는 finish_reason을 확인한 후 파싱합니다. max_tokens로 인해 응답이 중단되면 객체가 중간에 끊어질 수 있습니다. 잘못된 출력을 줄이기 위해 적절한 temperature를 사용합니다. 재시도 횟수를 제한하여 프롬프트가 무한히 반복되지 않도록 합니다. 실패한 요청은 요금이 부과되지 않으므로 재시도 예산은 비용보다 지연 시간 문제입니다.

자주 하는 JSON 모드 실수

  • 프롬프트에는 JSON을 요청하지만 response_format에는 설정하지 않음. 모델이 종종 따르지만, 객체를 텍스트나 코드 펜스 안에 감쌀 수 있습니다. 둘 다 설정하세요.
  • max_tokens을 너무 낮게 설정함. 가장 긴 유효한 답변을 추정하고 여유를 더하세요. 긴 항목 목록은 쉽게 300 토큰을 초과할 수 있습니다.
  • 최상위 배열을 기대함. JSON 모드는 객체를 요구합니다. 목록이 필요하면 {"items": [...]}을 요청하세요.
  • JSON에 나타나는 정지 시퀀스를 쌓음. stop 매개변수는 전달되며, 값 내부에 나타나는 정지 문자열은 응답을 짧게 잘라버립니다.
  • 스트리밍과 함께 JSON 모드를 사용하고 각 청크를 구문 분석함. 전체 텍스트를 먼저 수집한 후, 마지막에 한 번만 구문 분석하세요.

temperature, top_p, seed 및 페널티와 같은 샘플링 설정이 전달됩니다. 추출 작업의 경우 0.2 정도의 낮은 온도와 고정된 seed이 가장 반복 가능한 출력을 제공합니다. 위의 NPC와 같은 창의적 생성의 경우 검증만 한다면 높은 값도 괜찮습니다.

도구 호출: 전체 루프

도구 호출은 모델이 당신의 코드로 무언가를 하도록 요청한 후 결과를 가지고 계속 진행할 수 있게 합니다. 흐름은 네 단계로 구성됩니다: 도구를 선언하고, 모델이 tool_calls로 응답하며, 당신이 이를 실행하고, role: "tool" 메시지를 사용하여 결과를 다시 보냅니다.

import json, os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.uncensoredllmapi.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
)

tools = [{
    "type": "function",
    "function": {
        "name": "lookup_inventory",
        "description": "Return the stock count for an item in the shop.",
        "parameters": {
            "type": "object",
            "properties": {"item": {"type": "string"}},
            "required": ["item"],
        },
    },
}]

def lookup_inventory(item):
    stock = {"healing potion": 4, "rope": 12}
    return {"item": item, "count": stock.get(item.lower(), 0)}

messages = [{"role": "user", "content": "Do you still have healing potions?"}]

for _ in range(4):                      # hard cap on tool rounds
    r = client.chat.completions.create(
        model="uncensored", messages=messages, tools=tools, tool_choice="auto"
    )
    msg = r.choices[0].message
    if not msg.tool_calls:
        print(msg.content)
        break
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = lookup_inventory(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

인수는 JSON 문자열로 도착하며 구문 분석해야 하며, 모델은 때때로 스키마와 일치하지 않는 인수를 생성할 수 있습니다. 부작용이 있는 작업을 실행하기 전에 검증하세요. 체크 없이 셸, SQL 문자열 또는 파일 경로에 직접 전달하지 마세요.

tool_choice 필드는 동작을 조정할 수 있게 합니다. "auto"로 두면 모델이 결정합니다. 특정 함수 이름을 지정하면 호출을 강제할 수 있으며, 이는 JSON 모드 대신 도구 스키마를 통해 구조화된 추출을 원할 때 유용합니다.

Node에서 도구 호출 스트리밍

stream: true로 도구 호출은 조각으로 도착합니다. 각 청크는 함수 이름 또는 인수 문자열의 일부를 위치 인덱스로 포함합니다. 인덱스별로 조각을 연결하고 스트림이 끝날 때만 구문 분석해야 합니다.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.uncensoredllmapi.com/v1",
  apiKey: process.env.UNCENSORED_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Check stock for rope." }],
  tools: [{
    type: "function",
    function: {
      name: "lookup_inventory",
      description: "Return the stock count for an item.",
      parameters: {
        type: "object",
        properties: { item: { type: "string" } },
        required: ["item"],
      },
    },
  }],
});

const calls = [];
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta;
  for (const tc of delta?.tool_calls ?? []) {
    const slot = (calls[tc.index] ??= { id: "", name: "", args: "" });
    if (tc.id) slot.id = tc.id;
    if (tc.function?.name) slot.name += tc.function.name;
    if (tc.function?.arguments) slot.args += tc.function.arguments;
  }
}

for (const c of calls) {
  console.log(c.name, JSON.parse(c.args));
}

스트리밍 요청은 스트림이 끝날 때까지 동시 요청 슬롯 중 하나를 점유합니다. 전체 키는 동시 8개 요청과 분당 300개를 허용하며, 체험 키는 동시 2개와 분당 60개를 허용합니다. 한도에 도달하면 concurrency 또는 rate_limited 코드와 함께 HTTP 429가 반환됩니다. 사용량 총계는 스트림 종료 시 보고되므로 비용 로깅에 유용합니다.

JSON 모드 또는 도구 스키마

둘 다 구조화된 데이터를 제공하므로 어떤 것을 사용해야 할까요? 결정적인 질문은 모델이 데이터를 생성하는지 아니면 행동을 선택하는지입니다.

출력 자체가 제품인 경우 JSON 모드를 사용하세요: NPC 시트, 태그 목록, 신뢰도 필드가 있는 분류 등. 프롬프트 전체를 제어하고, 하나의 객체만 받으며, 하나의 요청에 대해 한 번만 지불합니다.

모델이 행동을 결정해야 하거나 여러 다른 행동이 가능한 경우 도구를 사용하세요. 함수별 스키마가 계약을 문서화하고, tool_choice로 호출을 강제하거나 허용할 수 있으며, 이전 섹션의 루프가 다단계 작업을 처리합니다. 비용은 라운드당 추가 요청과 도구 정의가 매번 입력으로 계산되는 것입니다.

추출을 위한 실용적인 중간 경로: 원하는 필드가 매개변수인 도구를 하나 선언하고, tool_choice을 해당 함수로 설정하세요. 프롬프트에 키 목록을 작성하지 않아도 스키마의 형태를 따르는 인수 JSON을 얻습니다. 어쨌든 결과를 신뢰하기 전에 검증하고, 예상치 못한 결과를 생성한 요청의 X-Request-Id 값을 로깅하세요.

비용 구조

JSON 및 도구 호출은 다른 모든 토큰처럼 청구됩니다: 입력 100만 토큰당 $0.15, 출력 100만 토큰당 $0.50. 도구 정의는 모든 요청에서 입력으로 계산되며, 다시 보내는 각 도구 결과는 다음 요청의 입력에 추가됩니다.

예시: 도구 사용 어시스턴트 턴은 600 토큰의 도구 스키마와 프롬프트, 150 토큰의 모델 호출을 포함하며, 이어서 이전 메시지들과 도구 결과를 포함하는 900 입력 토큰과 200 토큰의 응답을 포함하는 두 번째 요청이 있습니다.

  • 요청 1: 입력 600, 출력 150. 입력 600 x $0.15 / 1M = $0.00009. 출력 150 x $0.50 / 1M = $0.000075. 소계 $0.000165.
  • 요청 2: 입력 900, 출력 200. 입력 900 x $0.15 / 1M = $0.000135. 출력 200 x $0.50 / 1M = $0.0001. 소계 $0.000235.
  • 턴 총합: $0.0004.

그 비율로 1,000 턴에 $0.40가 듭니다. 크레딧은 $20부터 $500까지 전체 금액으로 선불 충전되며(보너스: $50부터 +5%, $100부터 +10%, $200부터 +15%), USDT(TRC20) 또는 USDC(Base)로 암호화폐 결제합니다. 현재 수치는 가격 책정 페이지에서 확인하세요.

다음 단계

모든 요청 필드의 레퍼런스는 API 문서에 있습니다. 실서비스 트래픽을 위한 애플리케이션을 준비 중이라면 프로덕션 체크리스트가 다음으로 읽어야 할 페이지이며, 요청이 예상과 다르게 동작할 경우 지원에서 도움을 받을 수 있습니다. X-Request-Id 헤더에 반환되는 요청 ID를 준비해 두세요.

서비스는 텍스트 전용이며 컨텍스트 창은 도구 정의와 결과를 포함해 100,000 토큰입니다. 미성년자가 포함된 성적인 콘텐츠는 허용되지 않으며, 이는 단순 채팅뿐만 아니라 구조화된 출력과 도구 기반 출력에도 동일하게 적용됩니다.

질문과 답변

JSON 모드가 정확한 스키마를 보장합니까?

아니요. 응답을 JSON 객체로 만들지만 키는 프롬프트에서 가져옵니다. 스키마 라이브러리로 결과를 검증하고 실패 시 재시도하세요.

도구 결과를 어떻게 다시 보내나요?

tool_calls를 포함한 어시스턴트 메시지를 추가한 후, role tool, 일치하는 tool_call_id 및 결과를 문자열로 하여 호출당 하나의 메시지를 추가하세요.

도구 호출을 스트리밍할 수 있나요?

네. stream을 true로 설정하면 tool_calls가 청크 단위로 도착합니다. 스트림이 끝나면 인덱스별로 name과 arguments 문자열을 연결한 후 한 번에 파싱하세요.

잘못된 JSON 응답에도 요금이 부과되나요?

응답이 완료되면 파서가 이를 거부하더라도 요금이 부과됩니다. 실패하거나 거부된 요청에는 요금이 청구되지 않습니다.

키는 양식 하나만 작성하면 받을 수 있습니다

계정을 생성하고 키를 복사한 후 기본 URL을 변경하세요. 설정은 이것으로 끝입니다.