Szybki start z curl
Najmniejsze działające zapytanie w trybie JSON wygląda tak. Używa base URL https://api.uncensoredllmapi.com/v1, modelu uncensored i twojego klucza jako tokenu 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."}
]
}'
Wiadomość asystenta w choices[0].message.content to string zawierający obiekt JSON. Musisz go sparsować samodzielnie. Nie pomijaj instrukcji w promptcie: tryb JSON ogranicza output do obiektu, ale nie zgadnie, jakich kluczy chcesz. Nazwanie kluczy i pokazanie jedno-liniowego przykładu daje stabilny kształt.
Jeśli nie masz jeszcze klucza, strona klucz API przyznaje $0.50 kredytu próbnego jednym kliknięciem po rejestracji. Ten kredyt nie wymaga płatności, trwa 7 dni i jest limitowany do jednego na osobę.
Tryb JSON w Pythonie z walidacją
Traktuj output modelu jak każde inne zewnętrzne wejście. Sparsuj go, sprawdź względem schematu i spróbuj ponownie ograniczoną liczbę razy, jeśli się nie powiedzie. Pydantic skraca ten proces:
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"))
Trzy nawyki w tym fragmencie są warte skopiowania. Kod sprawdza finish_reason przed parsowaniem, ponieważ odpowiedź kończąca się przy max_tokens kończy się w połowie obiektu. Używa umiarkowanej temperatury, ponieważ wysokie temperatury zwiększają prawdopodobieństwo niepoprawnego wyniku. I ogranicza liczbę ponownych prób, więc zły prompt nie może kręcić się w nieskończoność. Ponieważ nieudane lub odrzucone zapytania nie są rozliczane, budżet ponownych prób to kwestia opóźnienia, a nie kosztu.
Typowe błędy trybu JSON
- Prośba o JSON w promptcie, ale nie w
response_format. Model często się zgodzi, ale może owinąć obiekt w tekst lub kod. Ustaw oba. - Ustawienie
max_tokenszbyt nisko. Oceń najdłuższą poprawną odpowiedź i dodaj margines. Długa lista elementów łatwo przekroczy 300 tokenów. - Spodziewanie się tablicy na najwyższym poziomie. Tryb JSON żąda obiektu. Jeśli potrzebujesz listy, poproś o
{"items": [...]}. - Nakładanie sekwencji stop, która pojawia się w JSON. Parametr
stopjest przekazywany dalej, a ciąg stop, który pojawia się wewnątrz wartości, utnie odpowiedź. - Używanie trybu JSON ze strumieniowaniem i parsowaniem każdego fragmentu. Zbierz cały tekst najpierw, a potem sparsuj raz na końcu.
Ustawienia próbkowania takie jak temperatura, top_p, seed i kary są przekazywane. Dla zadań ekstrakcji niska temperatura około 0.2 i stały seed dają najbardziej powtarzalny wynik. Dla generacji kreatywnej jak NPC powyżej, wyższa wartość jest OK, dopóki walidujesz.
Wywoływanie funkcji: pełna pętla
Wywoływanie narzędzi pozwala modelowi poprosić twój kod o wykonanie czegoś, a następnie kontynuować z wynikiem. Przepływ ma cztery kroki: deklarujesz narzędzia, model odpowiada tool_calls, uruchamiasz je i wysyłasz wyniki z powrotem jako wiadomości z 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),
})
Argumenty przychodzą jako string JSON, który musisz sparsować, a model może czasami wyprodukować argumenty niepasujące do twojego schematu. Zweryfikuj je przed uruchomieniem czegokolwiek z efektami ubocznymi. Nigdy nie przesyłaj ich do powłoki, stringa SQL ani ścieżki pliku bez sprawdzania.
Pole tool_choice pozwala sterować zachowaniem. Zostaw "auto", a model zdecyduje. Nazwij konkretną funkcję, aby wymusić wywołanie, co jest przydatne, gdy chcesz ekstrakcję strukturalną przez schemat narzędzia zamiast trybu JSON.
Strumieniowanie wywołań funkcji w Node
Przy stream: true wywołania funkcji przychodzą w kawałkach. Każdy fragment niesie część nazwy funkcji lub ciągu argumentów, indeksowaną według pozycji. Musisz połączyć fragmenty według indeksu i sparsować dopiero, gdy strumień się zakończy.
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));
}
Pamiętaj, że zapytanie strumieniowe zajmuje jeden z twoich slotów równoległości do końca strumienia. Pełny klucz pozwala na 8 równoległych zapytań i 300 na minutę, klucz próbny na 2 i 60. Przekroczenie daje HTTP 429 z kodem concurrency lub rate_limited. Całkowite użycie jest raportowane na końcu strumienia, co jest przydatne do logowania kosztu.
Tryb JSON czy schemat narzędzia
Oba dają ci uporządkowane dane, więc którego użyć? Pytanie decydujące to, czy model produkuje dane, czy wybiera akcję.
Użyj trybu JSON, gdy outputem jest produkt: arkusz NPC, lista tagów, klasyfikacja z polem pewności. Kontrolujesz cały prompt, dostajesz jeden obiekt z powrotem i płacisz za jedno zapytanie.
Użyj narzędzi, gdy model musi zdecydować, czy działać, lub gdy możliwe jest kilka różnych akcji. Schemat dla każdej funkcji dokumentuje kontrakt, tool_choice pozwala wymusić lub zezwolić na wywołanie, a pętla w poprzednim rozdziale obsługuje pracę wielokrokową. Koszt to dodatkowe zapytanie na rundę, plus definicje narzędzi liczone jako input za każdym razem.
Praktyczna droga pośrednia dla ekstrakcji: zadeklaruj jedno narzędzie, którego parametry to pola, których chcesz, i ustaw tool_choice na tę funkcję. Dostajesz argument JSON, który podąża za kształtem schematu bez pisania listy kluczy w promptcie. W każdym razie zweryfikuj wynik, zanim mu uwierzysz, i zaloguj wartość X-Request-Id każdego zapytania, które wyprodukowało coś nieoczekiwanego.
Koszt
JSON i wywołania funkcji są rozliczane jak dowolne inne tokeny: $0.15 za 1M input i $0.50 za 1M output. Definicje narzędzi liczą się jako input w każdym zapytaniu, a każdy wynik narzędzia, który wyślesz z powrotem, dodaje się do inputu następnego zapytania.
Przykład: tura asystenta używającego narzędzia ze schematem narzędzia i promptem 600 tokenów, wywołaniem modelu 150 tokenów, a następnie drugim zapytaniem zawierającym 900 tokenów wejściowych (poprzednie wiadomości plus wynik narzędzia) i odpowiedzią 200 tokenów.
- Pierwsze zapytanie: 600 wejściowych i 150 wyjściowych. Wejście 600 x $0.15 / 1M = $0.00009. Wyjście 150 x $0.50 / 1M = $0.000075. Suma częściowa $0.000165.
- Drugie zapytanie: 900 wejściowych i 200 wyjściowych. Wejście 900 x $0.15 / 1M = $0.000135. Wyjście 200 x $0.50 / 1M = $0.0001. Suma częściowa $0.000235.
- Łącznie za turę: $0.0004.
W tym tempie 1 000 tur kosztuje $0,40. Kredyt jest przedpłacony w kwotach całkowitych od $20 do $500 (bonus: +5% od $50, +10% od $100, +15% od $200), płatny kryptowalutami USDT na TRC20 lub USDC na Base. Zobacz stronę z cenami, aby sprawdzić aktualne stawki.
Gdzie iść dalej
Opis każdego pola zapytania znajdziesz w dokumentacji API. Jeśli przygotowujesz aplikację do ruchu produkcyjnego, kolejną stroną do przeczytania jest lista kontrolna produkcyjna, a wsparcie pomoże, jeśli zapytanie zachowa się nieoczekiwanie. Zachowaj identyfikator zapytania zwracany w nagłówku X-Request-Id, aby mieć go pod ręką.
Usługa obsługuje tylko tekst, a okno kontekstu wynosi 100 000 tokenów, w tym definicje i wyniki twoich narzędzi. Treści o charakterze seksualnym z udziałem nieletnich są niedozwolone, a zasadę tę stosuje się do wyjścia sterowanego narzędziami tak samo jak do zwykłej rozmowy.
