VI ▾
Lấy khóa API
API không kiểm duyệt tương thích OpenAI dành cho nhà phát triển.Cập nhật

Chế độ JSON và gọi hàm của Uncensored LLM API

Công tắc chế độ JSON của uncensoredllmapi giống hệt những gì bạn đã biết từ các client OpenAI: hãy gửi response_format với type json_object và phản hồi sẽ trả về dưới dạng một đối tượng JSON. Trang này bao gồm điều đó, cùng với gọi hàm, với mã bạn có thể chạy trên endpoint trực tiếp.

Các ngoặc phát sáng được lắp ráp từ các khối lập phương bằng cánh tay cơ khí, minh họa cho đầu ra JSON có cấu trúc và các lệnh gọi hàm

Bắt đầu nhanh với curl

Yêu cầu chế độ JSON nhỏ nhất hoạt động giống như thế này. Nó sử dụng base URL https://api.uncensoredllmapi.com/v1, mô hình uncensored và khóa của bạn dưới dạng token 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."}
    ]
  }'

Tin nhắn assistant trong choices[0].message.content là một chuỗi chứa một đối tượng JSON. Bạn vẫn phải tự phân tích cú pháp nó. Đừng bỏ qua hướng dẫn trong prompt: chế độ JSON hạn chế đầu ra phải là một đối tượng, nhưng nó không thể đoán được các khóa bạn muốn. Đặt tên các khóa và lý tưởng nhất là hiển thị một ví dụ một dòng là những gì mang lại cho bạn một cấu trúc ổn định.

Nếu bạn chưa có khóa API, trang khóa API cấp $0,50 tín dụng dùng thử miễn phí chỉ với một cú nhấp chuột sau khi đăng ký. Tín dụng này không cần thanh toán, có hiệu lực trong 7 ngày và giới hạn một đơn vị cho mỗi người.

Chế độ JSON trong Python với xác thực

Hãy xử lý đầu ra của mô hình như bất kỳ đầu vào bên ngoài nào khác. Hãy phân tích cú pháp nó, kiểm tra nó với một schema và thử lại một số lần giới hạn nếu nó thất bại. Pydantic giúp việc này trở nên ngắn gọn:

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"))

Ba thói quen trong đoạn mã đó đáng để sao chép. Mã kiểm tra finish_reason trước khi phân tích, vì phản hồi dừng ở max_tokens sẽ bị ngắt giữa đối tượng. Nó dùng nhiệt độ vừa phải, vì nhiệt độ cao làm tăng khả năng tạo đầu ra sai định dạng. Và nó giới hạn số lần thử lại, nên prompt xấu không thể lặp vô hạn. Vì yêu cầu thất bại hoặc bị từ chối không bị tính phí, ngân sách thử lại là vấn đề về độ trễ chứ không phải chi phí.

Những lỗi phổ biến với chế độ JSON

  • Yêu cầu JSON trong prompt nhưng không trong response_format. Mô hình thường sẽ tuân thủ, nhưng có thể bọc đối tượng trong văn bản hoặc khối mã. Hãy đặt cả hai.
  • Đặt max_tokens quá thấp. Hãy ước lượng câu trả lời hợp lệ dài nhất và thêm phần dư. Một danh sách dài các mục có thể dễ dàng vượt quá 300 token.
  • Mong đợi một mảng cấp cao nhất. Chế độ JSON yêu cầu một đối tượng. Nếu bạn cần một danh sách, hãy yêu cầu {"items": [...]}.
  • Kết hợp một chuỗi dừng xuất hiện trong JSON. Tham số stop được truyền qua, và chuỗi dừng xuất hiện trong một giá trị sẽ cắt ngắn phản hồi.
  • Sử dụng chế độ JSON với streaming và phân tích cú pháp từng chunk. Hãy thu thập toàn bộ văn bản trước, sau đó phân tích cú pháp một lần vào cuối.

Các cài đặt lấy mẫu như temperature, top_p, seed và các điểm phạt được chuyển tiếp. Đối với các tác vụ trích xuất, nhiệt độ thấp khoảng 0.2 và seed cố định mang lại đầu ra có thể lặp lại nhất. Đối với việc tạo sáng tạo như NPC ở trên, một giá trị cao hơn là ổn miễn là bạn xác thực.

Gọi hàm: vòng lặp đầy đủ

Gọi hàm cho phép mô hình yêu cầu mã của bạn thực hiện một việc gì đó và sau đó tiếp tục với kết quả. Quy trình có bốn bước: bạn khai báo các công cụ, mô hình trả lời với tool_calls, bạn thực hiện chúng và gửi kết quả lại dưới dạng các tin nhắn với 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),
        })

Các đối số đến dưới dạng một chuỗi JSON, mà bạn phải phân tích cú pháp, và mô hình đôi khi có thể tạo ra các đối số không khớp với schema của bạn. Hãy xác thực chúng trước khi chạy bất kỳ thứ gì có tác dụng phụ. Đừng bao giờ chuyển chúng vào một shell, một chuỗi SQL hoặc một đường dẫn tệp mà không có các kiểm tra.

Trường tool_choice cho phép bạn định hướng hành vi. Hãy để nó ở "auto" và mô hình sẽ quyết định. Đặt tên một hàm cụ thể để buộc một lệnh gọi, điều này hữu ích khi bạn muốn trích xuất có cấu trúc thông qua một schema công cụ thay vì chế độ JSON.

Truyền phát các lệnh gọi hàm trong Node

Với stream: true, các lệnh gọi hàm đến dưới dạng các mảnh. Mỗi chunk mang theo một mảnh của tên hàm hoặc chuỗi đối số, được đánh chỉ mục theo vị trí. Bạn phải nối các mảnh theo chỉ mục và chỉ phân tích cú pháp khi stream kết thúc.

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));
}

Hãy nhớ rằng một yêu cầu streaming chiếm một trong các slot đồng thời của bạn cho đến khi stream kết thúc. Khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 mỗi phút, khóa dùng thử cho phép 2 và 60. Đạt một trong hai giới hạn sẽ trả về HTTP 429 với mã concurrency hoặc rate_limited. Tổng mức sử dụng được báo cáo ở cuối stream, rất hữu ích để ghi log chi phí.

Chế độ JSON hoặc schema công cụ

Cả hai đều cung cấp dữ liệu có cấu trúc, vậy bạn nên sử dụng cái nào? Câu hỏi quyết định là liệu mô hình có đang tạo dữ liệu hay đang chọn một hành động.

Hãy sử dụng chế độ JSON khi chính đầu ra là sản phẩm: một bảng NPC, một danh sách các thẻ, một phân loại với trường độ tin cậy. Bạn kiểm soát toàn bộ prompt, bạn nhận lại một đối tượng và có một yêu cầu để tính phí.

Sử dụng công cụ khi mô hình cần quyết định có nên thực hiện hành động hay không, hoặc khi có nhiều hành động khác nhau có thể xảy ra. Schema cho mỗi hàm mô tả hợp đồng, tool_choice cho phép bạn buộc hoặc cho phép gọi hàm, và vòng lặp ở phần trước xử lý công việc nhiều bước. Chi phí là một yêu cầu bổ sung mỗi lượt, cộng với định nghĩa công cụ được tính là đầu vào mỗi lần.

Một con đường trung gian thực tế cho việc trích xuất: khai báo một công cụ có các tham số là các trường bạn muốn, và đặt tool_choice thành hàm đó. Bạn nhận được JSON đối số tuân theo hình dạng schema của bạn mà không cần viết danh sách khóa vào prompt. Dù theo cách nào, hãy xác thực kết quả trước khi tin tưởng nó và ghi lại giá trị X-Request-Id của bất kỳ yêu cầu nào tạo ra điều gì đó không mong đợi.

Chi phí của bạn

JSON và các lệnh gọi hàm được tính phí như bất kỳ token nào khác: $0.15 cho mỗi 1M đầu vào và $0.50 cho mỗi 1M đầu ra. Các định nghĩa công cụ được tính là đầu vào trên mọi yêu cầu và mỗi kết quả công cụ bạn gửi lại sẽ thêm vào đầu vào của yêu cầu tiếp theo.

Ví dụ: một lượt trợ lý sử dụng công cụ với schema công cụ và prompt 600 token, một lệnh gọi mô hình 150 token, sau đó một yêu cầu thứ hai chứa 900 token đầu vào (các tin nhắn trước đó cộng với kết quả công cụ) và một phản hồi 200 token.

  • Yêu cầu một: 600 đầu vào và 150 đầu ra. Đầu vào 600 x $0.15 / 1M = $0.00009. Đầu ra 150 x $0.50 / 1M = $0.000075. Tổng phụ $0.000165.
  • Yêu cầu hai: 900 đầu vào và 200 đầu ra. Đầu vào 900 x $0.15 / 1M = $0.000135. Đầu ra 200 x $0.50 / 1M = $0.0001. Tổng phụ $0.000235.
  • Tổng cộng cho lượt đó: $0.0004.

Với tốc độ đó, 1.000 lượt hội thoại tốn $0,40. Tín dụng được trả trước theo số nguyên từ $20 đến $500 (tặng thêm: +5% từ $50, +10% từ $100, +15% từ $200), thanh toán bằng tiền mã hóa với USDT trên TRC20 hoặc USDC trên Base. Xem trang giá cả để biết số liệu hiện tại.

Đi tiếp ở đâu

Tham chiếu cho từng trường yêu cầu có trong tài liệu API. Nếu bạn đang chuẩn bị ứng dụng cho lưu lượng thực, danh sách kiểm sản xuất là trang tiếp theo bạn cần đọc, và hỗ trợ có thể giúp nếu một yêu cầu hoạt động không như mong đợi. Hãy giữ lại ID yêu cầu của bạn, xuất hiện trong tiêu đề X-Request-Id, để sẵn sàng sử dụng.

Dịch vụ chỉ hỗ trợ văn bản và cửa sổ ngữ cảnh là 100.000 token, bao gồm cả định nghĩa và kết quả công cụ của bạn. Nội dung tình dục liên quan đến người chưa thành niên không được phép, và điều này áp dụng cho đầu ra có cấu trúc và dựa trên công cụ giống như với trò chuyện thông thường.

Hỏi đáp

Chế độ JSON có đảm bảo đúng schema chính xác của tôi không?

Không. Nó biến phản hồi thành một đối tượng JSON, nhưng các khóa đến từ prompt của bạn. Hãy xác thực kết quả bằng thư viện schema và thử lại nếu thất bại.

Làm thế nào để gửi lại kết quả công cụ?

Hãy nối tin nhắn assistant chứa tool_calls, sau đó thêm một tin nhắn cho mỗi lệnh với role tool, tool_call_id tương ứng và kết quả dưới dạng chuỗi.

Tôi có thể truyền phát các lệnh gọi hàm không?

Có. Với stream đặt thành true, tool_calls đến dưới dạng các mảnh. Hãy nối chuỗi tên và đối số theo chỉ mục và phân tích cú pháp một lần khi stream kết thúc.

Các phản hồi JSON không hợp lệ có bị tính phí không?

Một phản hồi hoàn tất sẽ được tính phí, ngay cả khi trình phân tích cú pháp của bạn từ chối nó. Các yêu cầu thất bại hoặc bị từ chối sẽ không được tính phí.

Khóa của bạn chỉ cách một biểu mẫu

Tạo tài khoản, sao chép khóa, thay đổi URL cơ sở. Đó là toàn bộ thiết lập.