Çin uygulamaları oluşturma: istemler, yazı kontrolü ve UTF-8

Bağladığınız şey

Servis, POST /v1/chat/completions ve GET /v1/models uç noktalarını https://api.chinesellmapi.com/v1 altında sunar. Kimlik doğrulama bir Bearer anahtarı ile yapılır ve tek model kimliği uncensored'dir. Metin tabanlı bir API'dir ve tek bir modele sahiptir; bu nedenle seçim yapmanıza gerek yoktur: yerelleştirme işiniz tamamen istem içinde ve etrafındaki kendi kodunuzda gerçekleşir.

Herhangi bir şeyi tasarlamadan önce bilmeniz gereken limitler: istem ve tamamlama tarafından paylaşılan 100.000 token'lık bağlam penceresi, varsayılan olarak 2.048 olan ve 32.000 ile sınırlı max_tokens, 8 MB'a kadar istek gövdeleri ve anahtar başına dakikada 300 istek. Streaming (stream: true) SSE üzerinden çalışır ve OpenAI fonksiyon çağırma formatındaki araçlar kabul edilir.

Yeni hesaplar yedi gün boyunca geçerli olan $0,50 deneme kredisi alır, ödeme bilgisi gerekmez; bir e-posta ve şifre ile kaydolun ve anahtar hemen görünür. deneme SSS kuralları detaylı olarak kapsar.

Çince istemler yazın ve hangi Çince olduğunu belirtin

Karışık dildeki istemler, yerelleştirilmiş özelliklerde kayma kaynağıdır. Talimatlar İngilizceyse ancak içerik Çince ise, yanıtlar bazen İngilizce veya karışık gelebilir. Güvenli bir kalıp, hedef dilde yazılmış bir sistem istemidir; üç şeyi belirtir: rol, yazı tipi ve bölgesel sözcükler. Kullanıcı tarafından sağlanan metni talimatlarla karıştırılmaması için ayrı bir mesajda tutun.

İşte bir Basitleştirik Çince kurulumu. Sistem isteminin modeli yalnızca Basitleştirik karakterlerle yanıtlamasını ve yabancı İngilizce'den kaçınmasını (özel adlar istisna olmak üzere) söylediğine dikkat edin:

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)

İki alışkanlık hızlıca sonuç verir. Birincisi, istemleri kısa ve somut tutun: bir rol, bir çıktı formatı, bir veya iki kısıtlama. İkincisi, dil gereksinimini her kullanıcı dönüşünde tekrarlamak yerine sistem mesajına koyun, böylece konuşma geçmişi onu seyreltmez.

Basitleştirik ve Geleneksel çıktıyı kontrol etme

Yazı tipi seçimi, kullanıcı yerel ayarına bağlı bir ürün kararından ibarettir, bir model ayarı değil. Kıta odaklı ürünler Basitleştirik karakterler bekler; Tayvan ve Hong Kong kitleleri Geleneksel karakterler ve farklı sözcükler (yazılım, ağ ve veritabanı terimleri gibi) bekler. Pratik yaklaşım, yerel ayar etiketinizi bir sistem istemine eşlemektir ve seçimi kodda açık yapmaktır.

• zh-CN, zh-SG: Basitleştirilmiş, ana karada sözcük dağarcığı, yarım genişlikte rakamlar, tam genişlikte Çince noktalama işaretleri.
• zh-TW: Geleneksel, Tayvan sözcük dağarcığı, alıntılar için köşeli parantezler yaygındır.
• zh-HK: Geleneksel Hong Kong sözcükleriyle; ürününüzün sabit terimleri varsa kısa bir sözlük sağlayın.

Aynı çağrının Geleneksel varyantı şöyledir; yalnızca sistem istemi değişir:

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)

Modeller bazen diğer yazı tipinden birkaç karakter sızdırır, özellikle kullanıcı mesajı zaten diğer yazı tipindeyse. Ucuz bir son kontrol ekleyin ve daha katı bir talimatla bir kez daha deneyin. Örnek kontrolün ötesinde, OpenCC gibi özel bir dönüştürücü kütüphanesi aracılığıyla çıktıyı çalıştırın:

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

Diskten ağa ve geriye UTF-8

Çoğu bozuk Çince hatası model sorunları değildir. Bunlar, bir Windows konsolunun eski bir kod sayfası kullanması, kodlama olmadan açılan bir CSV dosyası veya içerik türünü yeniden yazan bir proxy gibi, boru hattındaki varsayılan bir kodlamadan kaynaklanır. Her sınırı açık hale getirin.

Python'da, encoding="utf-8"'i open'e geçirin ve JSON'u elle oluşturuyorsanız, ensure_ascii=False'i takip eden .encode("utf-8")'i kullanın. Aşağıdaki örnek, düz requests ile bunu yapar ve ayrıca çağrının ham HTTP şeklini gösterir:

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

Node.js'te, readFile bir Encoding sağlamazdığınız sürece bir Buffer döndürür ve kaynak dosya UTF-8 olarak kaydedildiği sürece Çin karakterleri içeren şablon dizeleri sorun çıkarmaz. Resmi SDK gövdeyi sizin için seri hale getirir:

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

İki tuzak daha. Dizeleri bayt uzunluğuna göre kısaltmak bir karakteri ikiye bölebilir, bu yüzden her zaman karakterlere göre dilimleyin. Ve akış yaparken, çok baytlı bir karakter ağ paketleri arasında bölünebileceğinden, akışı artımlı olarak UTF-8 olarak çözümlen. SDK'lar bunu halleder ancak elle yazılmış ayrıştırıcılar genellikle halledemez.

Çince metin için token bütçelemesi

Çince'de boşluk yoktur, bu yüzden kelime sayıları bütçeleme için anlamsızdır. Bir planlama varsayımı olarak, ölçülmüş bir sabit olarak değil, bir Çince karakteri yaklaşık 1 ila 2 token olarak değerlendirin ve tek bir sayı gerektiğinde 1.5 kullanın. Metne gömülü Latin kelimeler ve rakamlar kelime başına yaklaşık 1.3 token'e yakındır. Oran kelime dağarcığına göre değişir, bu yüzden tek yetkili rakam, her yanıtla birlikte döndürülen usage nesnesidir.

Küçük bir yardımcı, göndermeden önce bir istemi tahmin etmeyi ve zaman içinde gerçek kullanıma göre oranları ayarlamayı kolaylaştırır:

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

Varsayımlar açıkça belirtilmiş bir örnek: karakter başına 1,5 token ile 2.000 karakterlik bir makale yaklaşık 3.000 giriş token'ıdır. 400 karakterlik bir özet yaklaşık 600 çıktı token'ıdır. Milyon giriş token'ı başına $0,25 ve milyon çıktı token'ı başına $1,00 ile, bir çağrı giriş için yaklaşık $0,00075 ve çıktı için $0,0006, toplamda yaklaşık $0,00135'e mal olur. Bağlam 100.000 token ile sınırlı olduğundan, aynı varsayım yaklaşık 40.000 karakterlik bir istemin bir yanıt için yer bırakacağı anlamına gelir.

Uzun belgeleri beslemeniz gerektiğinde, paragraf veya başlık bazında parçalara ayırın, asla cümle ortasında değil ve max_tokens'i açıkça belirtin. Fiyatlar ve limitler fiyatlandırma sayfasında listelenmiştir.

Çoklu dönüşlü Çin sohbetini pencere içinde tutma

Sohbet özellikleri her istekte tüm geçmişi yeniden gönderir, bu nedenle maliyet ve bağlam her adımda artar. Pencere, istem ve tamamlama arasında paylaşılan 100.000 token olduğundan, bir şey yapmazsanız uzun bir konuşma sonunda bir 400 hatası tetikler. Hatalara tepki vermek yerine bir kısaltma politikası erkenden belirleyin.

Basit bir politika, sistem istemini tutmak, tahmini istemin bir bütçeye sığması kadar en eski dönüşleri kaldırmak ve kalan kısmı yanıta ayırmaktır. Aşağıdaki taslak, önceki bölümdeki tahmin ediciyi yeniden kullanır:

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

Erken bağlamın önemli olduğu ürünler için, örneğin bir özel ders botu veya destek asistanı, atılan dönüşleri doğrudan atmak yerine kısa bir özet mesajla değiştirin. Modelden eski dönüşleri konuşmanın aynı yazı tipinde birkaç cümleye sıkıştırmayı isteyin, ardından bu özeti sistem isteminin hemen sonrasına yerleştirin. Bu, her ara bir ek çağrı maliyeti taşır ve kişiliği ve gerçekleri sabit tutar.

Ayrıca sohbet için max_tokens'i makul bir şekilde sınırlandırmayı unutmayın. Bir mesajlaşma arayüzündeki yanıtlar genellikle birkaç yüz token'dan fazlasına ihtiyaç duymaz ve daha sıkı bir sınır hem gecikmeyi hem de maliyeti daha öngörülebilir hale getirir. Yanıtı token token akış yapmak algılanan hızı artırır, özellikle Çin metninde kullanıcılar kısa aralıklarla okuduğu için.

Ön lansman kontrol listesi ve sonraki adımlar

1. Her yerel ayarı bir sistem istemine eşleyin ve eşlemeyi birim test edin.
2. Dosya okuma, istek gövdeleri ve günlüklerde kodlamaları açıkça ayarlayın.
3. Her özellik için usage'ı günlüğe kaydedin ve haftalık olarak kestirimcinizle karşılaştırın.
4. 402 (no_credit), 429 ve 503 (upstream_busy) hatalarını farklı şekilde işleyin: bakiye yükleyin, yavaşlayın, birkaç saniye sonra yeniden deneyin.
5. 403 (content_blocked) hatasını, yeniden deneme durumu değil, o istek için nihai bir yanıt olarak ele alın.

Uygulamanız çeviri hatları içeriyorsa, çeviri ve yerelleştirme kılavuzuna devam edin; seri kurgu ve karakter sohbeti için web kurgu kılavuzuna bakın. Tam parametre referansı dokümantasyonda yer alır.