Xây dựng ứng dụng tiếng Trung: prompt, kiểm soát bộ ký tự và UTF-8

Những gì bạn đang kết nối

Service cung cấp POST /v1/chat/completions và GET /v1/models tại https://api.chinesellmapi.com/v1. Xác thực bằng khóa bearer, và model id duy nhất là uncensored. Đây là API chỉ xử lý văn bản với một mô hình, nên bạn không cần phải chọn giữa các tùy chọn: công việc bản địa hóa của bạn diễn ra hoàn toàn trong prompt và trong mã của bạn xung quanh nó.

Các giới hạn bạn nên biết trước khi thiết kế: cửa sổ ngữ cảnh 100.000 token dùng chung cho prompt và kết quả, max_tokens mặc định là 2.048 với trần là 32.000, thân yêu cầu tối đa 8 MB, và 300 yêu cầu mỗi phút trên mỗi khóa. Truyền phát (stream: true) hoạt động qua server-sent events, và các công cụ theo định dạng gọi hàm OpenAI được chấp nhận.

Tài khoản mới nhận được tín dụng dùng thử miễn phí $0.50 trong bảy ngày, không cần thông tin thanh toán; đăng ký bằng email và mật khẩu và khóa sẽ xuất hiện ngay lập tức. FAQ về bản dùng thử giải thích chi tiết các quy tắc.

Viết prompt bằng tiếng Trung, và nói rõ loại tiếng Trung nào

Prompt hỗn hợp ngôn ngữ là nguồn gốc phổ biến nhất của sự lệch hướng trong các tính năng bản địa hóa. Nếu hướng dẫn bằng tiếng Anh nhưng nội dung là tiếng Trung, phản hồi đôi khi trả về bằng tiếng Anh hoặc hỗn hợp. Một mẫu đáng tin cậy là một prompt hệ thống viết bằng ngôn ngữ mục tiêu, nêu ba điều: vai trò, bộ ký tự và từ vựng khu vực. Giữ văn bản do người dùng cung cấp trong một tin nhắn riêng để nó không bị nhầm là hướng dẫn.

Dưới đây là thiết lập tiếng Trung Giản thể. Lưu ý rằng prompt hệ thống yêu cầu mô hình chỉ trả lời bằng ký tự Giản thể và tránh tiếng Anh thừa, với danh từ riêng là ngoại lệ:

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)

Hai thói quen mang lại hiệu quả nhanh chóng. Thứ nhất, giữ prompt ngắn gọn và cụ thể: một vai trò, định dạng đầu ra, một hoặc hai ràng buộc. Thứ hai, đặt yêu cầu ngôn ngữ trong tin nhắn hệ thống thay vì lặp lại nó trong mỗi lượt người dùng, để lịch sử hội thoại không làm loãng nó.

Kiểm soát đầu ra Giản thể so với Phồn thể

Lựa chọn bộ ký tự là quyết định sản phẩm gắn với locale người dùng, không phải cài đặt mô hình. Sản phẩm hướng đại lục mong đợi ký tự Giản thể; người dùng Đài Loan và Hồng Kông mong đợi Phồn thể, với từ vựng khác nhau (các ví dụ thường gặp là thuật ngữ phần mềm, mạng và cơ sở dữ liệu). Cách tiếp cận thực tế là ánh xạ thẻ locale của bạn thành một prompt hệ thống và đưa ra lựa chọn rõ ràng trong mã.

• zh-CN, zh-SG: Giản thể, từ vựng đại lục, chữ số bán rộng, dấu câu tiếng Trung toàn rộng.
• zh-TW: Phồn thể, từ vựng Đài Loan, ngoặc góc thường dùng cho trích dẫn.
• zh-HK: Phồn thể với từ vựng Hồng Kông; hãy cung cấp một bảng từ vựng ngắn nếu sản phẩm của bạn có các thuật ngữ cố định.

Biến thể Phồn thể của cùng một lệnh gọi trông như thế này; chỉ prompt hệ thống thay đổi:

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)

Mô hình đôi khi rò rỉ một vài ký tự của bộ ký tự khác, đặc biệt khi tin nhắn người dùng chính là bộ ký tự kia. Thêm một bước kiểm tra hậu kỳ rẻ tiền và thử lại một lần với hướng dẫn mạnh mẽ hơn nếu nó bị lỗi. Đối với bất kỳ thứ gì vượt quá kiểm tra mẫu, hãy chạy đầu ra qua thư viện chuyển đổi chuyên dụng như 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 từ đĩa đến đường truyền và ngược lại

Hầu hết các lỗi tiếng Trung bị lỗi mã hóa không phải là vấn đề mô hình. Chúng đến từ một mã hóa mặc định ở đâu đó trong quy trình: bảng mã kế thừa của console Windows, một tệp CSV được mở mà không có mã hóa, một proxy ghi lại loại nội dung. Hãy làm rõ mọi ranh giới.

Trong Python, hãy truyền encoding="utf-8" vào open, và nếu bạn tự xây dựng JSON, hãy sử dụng ensure_ascii=False kèm theo .encode("utf-8"). Ví dụ dưới đây thực hiện điều này với requests thông thường, cũng cho thấy cấu trúc HTTP thô của lệnh gọi:

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

Trong Node, readFile trả về một Buffer trừ khi bạn cung cấp mã hóa, và các chuỗi mẫu chứa tiếng Trung đều ổn miễn là file nguồn được lưu dưới dạng UTF-8. SDK chính thức sẽ tự động tuần tự hóa thân yêu cầu cho bạn:

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

Hai bẫy khác. Cắt xén chuỗi theo độ dài byte có thể cắt ngang một ký tự, vì vậy hãy luôn cắt theo ký tự. Và khi bạn truyền phát, hãy giải mã luồng dưới dạng UTF-8 theo từng phần, vì một ký tự nhiều byte có thể bị chia cắt giữa các gói mạng; các SDK xử lý việc này, nhưng các trình phân tích tùy chỉnh thường không làm được.

Tính toán token cho văn bản tiếng Trung

Tiếng Trung không có khoảng trắng, vì vậy đếm từ không hữu ích để tính toán ngân sách. Với giả định lập kế hoạch, không phải là hằng số đo lường, hãy coi một ký tự tiếng Trung tương đương khoảng 1 đến 2 token, và sử dụng 1.5 khi bạn cần một con số duy nhất. Các từ tiếng Latinh và chữ số xen kẽ trong văn bản gần bằng 1.3 token mỗi từ. Tỷ lệ này thay đổi tùy theo từ vựng, vì vậy con số chính xác nhất là đối tượng usage được trả về cùng với mọi phản hồi.

Một tiện ích nhỏ giúp dễ dàng ước lượng một prompt trước khi gửi nó, và tinh chỉnh các tỷ lệ dựa trên việc sử dụng thực tế theo thời gian:

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

Ví dụ chi tiết, với các giả định được nêu rõ: một bài viết 2.000 ký tự với 1.5 token mỗi ký tự là khoảng 3.000 token đầu vào. Một tóm tắt 400 ký tự là khoảng 600 token đầu ra. Với giá $0.25 cho mỗi triệu token đầu vào và $1.00 cho mỗi triệu token đầu ra, một lệnh gọi tốn khoảng $0.00075 cho đầu vào cộng $0.0006 cho đầu ra, tổng cộng khoảng $0.00135. Vì ngữ cảnh bị giới hạn ở 100.000 token, giả định tương tự có nghĩa là một prompt khoảng 40.000 ký tự sẽ còn chỗ cho phản hồi.

Khi bạn phải xử lý các tài liệu dài, hãy chia nhỏ theo đoạn hoặc tiêu đề, không bao giờ chia giữa câu, và hãy giữ max_tokens rõ ràng. Giá và giới hạn được liệt kê trên trang giá cả.

Giữ hội thoại tiếng Trung nhiều lượt trong cửa sổ ngữ cảnh

Các tính năng trò chuyện gửi lại toàn bộ lịch sử trên mỗi yêu cầu, vì vậy chi phí và ngữ cảnh tăng lên theo mỗi lượt. Vì cửa sổ là 100.000 token dùng chung giữa prompt và kết quả, một cuộc hội thoại dài cuối cùng sẽ kích hoạt lỗi 400 nếu bạn không làm gì. Hãy quyết định chính sách cắt giảm sớm hơn là phản ứng với lỗi.

Một chính sách đơn giản là giữ prompt hệ thống, loại bỏ các lượt cũ nhất cho đến khi prompt ước lượng phù hợp với ngân sách, và dành phần còn lại cho câu trả lời. Bản phác thảo dưới đây tái sử dụng bộ ước lượng từ phần trước:

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

Đối với các sản phẩm mà ngữ cảnh sớm quan trọng, chẳng hạn như bot gia sư hoặc trợ lý hỗ trợ, hãy thay thế các lượt bị loại bằng một tin nhắn tóm tắt ngắn thay vì loại bỏ chúng hoàn toàn. Yêu cầu mô hình nén các lượt cũ thành một vài câu bằng cùng bộ ký tự với cuộc hội thoại, sau đó chèn bản tóm tắt đó ngay sau prompt hệ thống. Nó tốn một lệnh gọi bổ sung mỗi khi và giữ nhân vật và sự thật ổn định.

Ngoài ra, hãy nhớ giới hạn max_tokens một cách hợp lý cho trò chuyện. Các phản hồi trong giao diện nhắn tin hiếm khi cần hơn vài trăm token, và việc giới hạn chặt chẽ hơn giúp độ trễ và chi phí dễ dự đoán hơn hơn. Truyền phát phản hồi từng token giúp cải thiện tốc độ cảm nhận, đặc biệt là với văn bản tiếng Trung nơi người dùng đọc theo từng đoạn ngắn.

Danh sách kiểm tra trước khi ra mắt và các bước tiếp theo

1. Ánh xạ mỗi locale thành một prompt hệ thống và kiểm thử đơn vị ánh xạ đó.
2. Đặt mã hóa rõ ràng trong đọc tệp, thân yêu cầu và nhật ký.
3. Ghi lại usage theo từng tính năng và so sánh nó với bộ ước lượng của bạn hàng tuần.
4. Xử lý 402 (no_credit), 429 và 503 (upstream_busy) khác nhau: nạp tiền, giảm tốc độ, thử lại sau vài giây.
5. Hãy coi 403 (content_blocked) là câu trả lời cuối cùng cho yêu cầu đó, không phải trường hợp thử lại.

Nếu ứng dụng của bạn liên quan đến quy trình dịch thuật, hãy tiếp tục với hướng dẫn dịch thuật và bản địa hóa; đối với văn học mạng và trò chuyện nhân vật, hãy xem hướng dẫn văn học mạng. Tài liệu tham khảo đầy đủ về các tham số có trong tài liệu.