Membangun aplikasi bahasa Mandarin: prompt, kontrol skrip dan UTF-8

Yang Anda sambungkan

Layanan ini mengekspos POST /v1/chat/completions dan GET /v1/models di bawah https://api.chinesellmapi.com/v1. Autentikasi menggunakan kunci bearer, dan satu-satunya id model adalah uncensored. Ini adalah API teks-only dengan satu model, jadi tidak ada yang perlu dipilih: pekerjaan lokalisasi Anda terjadi sepenuhnya dalam prompt dan dalam kode Anda di sekitarnya.

Batas yang perlu diketahui sebelum Anda merancang apa pun: jendela konteks 100.000 token yang dibagikan oleh prompt dan completion, max_tokens yang secara default bernilai 2.048 dengan batas atas 32.000, tubuh permintaan hingga 8 MB, dan 300 permintaan per menit per kunci. Streaming (stream: true) bekerja melalui server-sent events, dan alat dalam format function-calling OpenAI diterima.

Akun baru mendapatkan kredit uji coba senilai $0,50 yang berlaku selama tujuh hari, tanpa memerlukan detail pembayaran; daftar dengan email dan kata sandi dan kunci muncul segera. FAQ trial mencakup aturan secara rinci.

Tulis prompt dalam bahasa Mandarin, dan sebutkan bahasa Mandarin mana

Prompt campuran bahasa adalah sumber pergeseran paling umum dalam fitur yang dilokalkan. Jika instruksi dalam bahasa Inggris tetapi konten dalam bahasa Mandarin, balasan kadang-kadang kembali dalam bahasa Inggris atau campuran. Pola yang andal adalah prompt sistem yang ditulis dalam bahasa target, menyatakan tiga hal: peran, skrip, dan kosakata regional. Pertahankan teks yang disediakan pengguna dalam pesan terpisah agar tidak dianggap sebagai instruksi.

Berikut adalah pengaturan Simplified Chinese. Perhatikan bahwa system prompt memberi tahu model untuk menjawab hanya dalam karakter Simplified dan menghindari bahasa Inggris yang tersesat, dengan nama proper sebagai pengecualian:

Copyimport os
from openai import OpenAI

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

SYSTEM_SC = (
    "你是一名产品文案助手。始终使用简体中文回答，使用中国大陆常见的用词和标点，"
    "不要夹杂繁体字或英文句子，专有名词除外。"
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": SYSTEM_SC},
        {"role": "user", "content": "为一款记账应用写三条应用商店的一句话简介。"},
    ],
    max_tokens=300,
    temperature=0.7,
)
print(resp.choices[0].message.content)
print(resp.usage)

Dua kebiasaan memberikan hasil cepat. Pertama, pertahankan prompt pendek dan konkret: peran, format output, satu atau dua batasan. Kedua, masukkan persyaratan bahasa dalam pesan sistem daripada mengulanginya di setiap giliran pengguna, agar riwayat percakapan tidak mengencerkan instruksi tersebut.

Mengontrol output Sederhana vs Tradisional

Pilihan skrip adalah keputusan produk yang terkait dengan locale pengguna, bukan pengaturan model. Produk yang berorientasi daratan mengharapkan karakter Sederhana; audiens Taiwan dan Hong Kong mengharapkan Tradisional, dengan kosakata yang berbeda juga (contoh yang biasa adalah istilah perangkat lunak, jaringan, dan basis data). Pendekatan praktisnya adalah memetakan tag locale Anda ke prompt sistem dan membuat pilihan secara eksplisit dalam kode.

• zh-CN, zh-SG: Simplified, kosakata daratan, digit setengah lebar, tanda baca Mandarin lebar penuh.
• zh-TW: Traditional, kosakata Taiwan, tanda kutip sudut sering digunakan.
• zh-HK: Tradisional dengan kata-kata Hong Kong; sediakan glosarium singkat jika produk Anda memiliki istilah tetap.

Varian Tradisional dari panggilan yang sama terlihat seperti ini; hanya prompt sistem yang berubah:

Copyimport os
from openai import OpenAI

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

SYSTEM_TC = (
    "你是一名產品文案助手。請一律使用繁體中文回答，採用臺灣常用的詞彙與全形標點，"
    "例如「軟體」「網路」「資料庫」，不要混入簡體字。"
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": SYSTEM_TC},
        {"role": "user", "content": "請用兩句話說明什麼是雙重驗證。"},
    ],
    max_tokens=200,
)
print(resp.choices[0].message.content)

Model kadang-kadang membocorkan beberapa karakter dari skrip lainnya, terutama ketika pesan pengguna sendiri berada dalam skrip lainnya. Tambahkan pemeriksaan pasca yang murah dan coba lagi sekali dengan instruksi yang lebih tegas jika terjadi kesalahan. Untuk apa pun di luar pemeriksaan sampel, jalankan output melalui pustaka konverter khusus seperti OpenCC:

Copy# A cheap guard: flag replies that contain characters that exist only in Simplified.
# The set below is a small sample, not a full list; use a converter such as OpenCC
# for production-grade checks.
SIMPLIFIED_ONLY = set("这个们说话时间书买卖东车门开关见觉")

def looks_simplified(text: str) -> bool:
    return any(ch in SIMPLIFIED_ONLY for ch in text)

reply = "請用繁體中文回覆的範例文字"
print(looks_simplified(reply))   # False

UTF-8 dari disk ke jaringan dan kembali

Sebagian besar bug Chinese yang rusak bukan masalah model. Masalah ini berasal dari pengkodean default di suatu tempat dalam pipeline: konsol Windows yang menggunakan halaman kode lama, CSV yang dibuka tanpa encoding, proxy yang menulis ulang tipe konten. Jadikan setiap batas eksplisit.

Dalam Python, sertakan encoding="utf-8" ke open, dan jika Anda membuat JSON secara manual, gunakan ensure_ascii=False diikuti oleh .encode("utf-8"). Contoh di bawah ini melakukannya dengan requests biasa, yang juga menunjukkan bentuk HTTP mentah dari panggilan tersebut:

Copyimport json
import os
import requests

# 1) Always open files as UTF-8, never rely on the platform default encoding.
with open("notes_zh.txt", "r", encoding="utf-8") as f:
    note = f.read()

payload = {
    "model": "uncensored",
    "messages": [{"role": "user", "content": "请把下面的笔记整理成三个要点：\n" + note}],
    "max_tokens": 400,
}

# 2) requests encodes json= as UTF-8 for you. If you build the body by hand,
#    keep Chinese readable and make the encoding explicit.
body = json.dumps(payload, ensure_ascii=False).encode("utf-8")

r = requests.post(
    "https://api.chinesellmapi.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer " + os.environ["API_KEY"],
        "Content-Type": "application/json; charset=utf-8",
    },
    data=body,
    timeout=60,
)
r.raise_for_status()
r.encoding = "utf-8"
print(r.json()["choices"][0]["message"]["content"])

Di Node, readFile mengembalikan Buffer kecuali Anda menyediakan encoding, dan string template yang berisi Chinese baik-baik saja selama file sumber itu sendiri disimpan sebagai UTF-8. SDK resmi menserialisasi tubuh untuk Anda:

Copyimport { readFile } from "node:fs/promises";
import OpenAI from "openai";

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

// Pass "utf8" explicitly; without it readFile returns a Buffer, not a string.
const note = await readFile("notes_zh.txt", "utf8");

const res = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: `请把下面的笔记整理成三个要点：\n${note}` }],
  max_tokens: 400,
});

console.log(res.choices[0].message.content);
console.log(res.usage);

Dua jebakan lagi. Memotong string berdasarkan panjang byte dapat memotong karakter menjadi dua, jadi selalu iris berdasarkan karakter. Dan saat Anda streaming, dekode stream sebagai UTF-8 secara inkremental, karena karakter multi-byte dapat terpecah di antara potongan jaringan; SDK menangani ini, tetapi parser yang dibuat manual sering kali tidak.

Menganggarkan token untuk teks Mandarin

Mandarin tidak memiliki spasi, sehingga penghitungan kata tidak berguna untuk penganggaran. Sebagai asumsi perencanaan, bukan konstanta terukur, anggap satu karakter Mandarin sekitar 1 hingga 2 token, dan gunakan 1,5 ketika Anda membutuhkan satu angka. Kata-kata Latin dan digit yang disisipkan dalam teks lebih dekat ke 1,3 token per kata. Rasio bervariasi dengan kosakata, sehingga satu-satunya angka otoritatif adalah objek usage yang dikembalikan dengan setiap respons.

Pembantu kecil membuatnya mudah untuk memperkirakan prompt sebelum Anda mengirimkannya, dan untuk menyesuaikan rasio terhadap penggunaan nyata dari waktu ke waktu:

Copyimport re

CJK = re.compile(r"[㐀-鿿＀-￯　-〿]")

def rough_tokens(text: str, per_cjk: float = 1.5, per_other_word: float = 1.3) -> int:
    """Planning estimate only. The 1.5 and 1.3 ratios are assumptions, not
    measured values; compare against resp.usage and adjust them."""
    cjk = len(CJK.findall(text))
    others = len(re.findall(r"[A-Za-z0-9_]+", CJK.sub(" ", text)))
    return round(cjk * per_cjk + others * per_other_word)

sample = "订单 A-1042 已发货，预计周三送达。"
print(rough_tokens(sample))

Contoh kerja, dengan asumsi yang dinyatakan: artikel 2.000 karakter pada 1,5 token per karakter adalah sekitar 3.000 token input. Ringkasan 400 karakter adalah sekitar 600 token output. Pada $0,25 per juta token input dan $1,00 per juta token output, satu panggilan memakan biaya sekitar $0,00075 untuk input ditambah $0,0006 untuk output, sekitar $0,00135 secara total. Karena konteks dibatasi pada 100.000 token, asumsi yang sama berarti prompt sekitar 40.000 karakter menyisakan ruang untuk balasan.

Ketika Anda harus memberi makan dokumen panjang, pecah per paragraf atau judul, jangan pernah di tengah kalimat, dan pertahankan max_tokens secara eksplisit. Harga dan batas tercantum di halaman harga.

Menjaga percakapan Mandarin multi-giliran dalam jendela

Fitur chat mengirim ulang seluruh riwayat pada setiap permintaan, sehingga biaya dan konteks tumbuh dengan setiap giliran. Karena jendela tersebut adalah 100.000 token yang dibagikan antara prompt dan completion, percakapan panjang akhirnya memicu 400 jika Anda tidak melakukan apa-apa. Putuskan kebijakan pemangkasan lebih awal daripada bereaksi terhadap kesalahan.

Kebijakan sederhana adalah mempertahankan prompt sistem, menghapus giliran tertua hingga perkiraan prompt sesuai dengan anggaran, dan menyimpan sisa sisanya untuk jawaban. Sketsa di bawah ini menggunakan estimator dari bagian sebelumnya:

CopyMAX_PROMPT_TOKENS = 48_000   # leave headroom under the 100,000 window for the reply

def trim_history(messages, estimate):
    # messages[0] is the system prompt and is always kept
    system, rest = messages[0], messages[1:]
    while rest and sum(estimate(m["content"]) for m in [system] + rest) > MAX_PROMPT_TOKENS:
        rest.pop(0)   # drop the oldest turn first
    return [system] + rest

Untuk produk di mana konteks awal penting, seperti bot tutor atau asisten dukungan, ganti giliran yang dihapus dengan pesan ringkasan pendek daripada membuangnya secara langsung. Minta model untuk memampatkan giliran lama menjadi beberapa kalimat dalam skrip yang sama dengan percakapan, lalu sisipkan ringkasan itu tepat setelah prompt sistem. Ini membutuhkan satu panggilan tambahan setiap kali dan menjaga persona dan fakta tetap stabil.

Juga ingat untuk membatasi max_tokens secara wajar untuk chat. Balasan dalam UI pesan jarang membutuhkan lebih dari beberapa ratus token, dan batas yang lebih ketat membuat latensi dan biaya lebih dapat diprediksi. Streaming balasan token per token membantu kecepatan persepsi, terutama untuk teks Mandarin di mana pengguna membaca dalam serbuan pendek.

Daftar periksa pra-peluncuran dan langkah selanjutnya

1. Petakan setiap locale ke prompt sistem dan uji unit pemetaan.
2. Setel encoding secara eksplisit dalam pembacaan file, badan permintaan, dan log.
3. Log usage per fitur dan bandingkan dengan estimator Anda setiap minggu.
4. Tangani 402 (no_credit), 429 dan 503 (upstream_busy) secara berbeda: isi ulang, kurangi laju, coba lagi setelah beberapa detik.
5. Perlakukan 403 (content_blocked) sebagai jawaban akhir untuk permintaan tersebut, bukan kasus percobaan ulang.

Jika aplikasi Anda melibatkan pipeline terjemahan, lanjutkan dengan panduan terjemahan dan lokalisasi; untuk fiksi berseri dan obrolan karakter, lihat panduan fiksi web. Referensi parameter lengkap ada di dokumen.