중국어 앱 빌드: 프롬프트, 문자 제어 및 UTF-8

연결할 항목

서비스는 POST /v1/chat/completions 및 GET /v1/models 엔드포인트를 https://api.chinesellmapi.com/v1 아래에 제공합니다. 인증은 베어러 키를 사용하며, 유일한 모델 ID는 uncensored입니다. 텍스트 전용 API로 모델이 하나뿐이므로 선택할 항목이 없습니다. 로컬라이제이션 작업은 프롬프트와 이를 둘러싼 자체 코드에서 모두 수행됩니다.

설계 전에 알아야 할 제한 사항: 프롬프트와 완성을 공유하는 100,000 토큰 컨텍스트 창, 기본값 2,048이고 최대 32,000인 max_tokens, 최대 8 MB의 요청 본문, 키당 분당 300 요청입니다. 스트리밍(stream: true)은 서버 전송 이벤트(SSE)를 통해 작동하며, OpenAI 함수 호출 형식의 도구를 지원합니다.

새 계정에는 7일 동안 유효한 $0.50 무료 체험 크레딧이 지급되며, 결제 정보는 필요하지 않습니다. 이메일과 비밀번호로 등록하면 키가 즉시 표시됩니다. 무료 체험 FAQ에는 규칙이 자세히 나와 있습니다.

프롬프트를 중국어로 작성하고, 어떤 중국어인지 명시하세요

혼합 언어 프롬프트는 로컬라이즈된 기능에서 드리프트가 발생하는 가장 흔한 원인입니다. 지시사항이 영어로 되어 있지만 콘텐츠가 중국어인 경우, 응답이 영어나 혼합어로 반환되기도 합니다. 신뢰할 수 있는 패턴은 대상 언어로 작성된 시스템 프롬프트를 사용하여 역할, 문자 및 지역 어휘를 명시하는 것입니다. 사용자 제공 텍스트는 별도 메시지로 유지하여 지시사항과 혼동되지 않도록 하세요.

다음은 간체 중국어 설정 예시입니다. 시스템 프롬프트는 모델이 간체 문자로만 답변하고 고유명을 제외하고 영어를 피하도록 지시합니다:

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)

두 가지 습관이 빠르게 효과를 냅니다. 첫째, 프롬프트를 짧고 구체적으로 유지하세요: 역할, 출력 형식, 하나 또는 두 가지 제약 사항. 둘째, 언어 요구사항을 매 사용자 턴마다 반복하기보다 시스템 메시지에 포함하세요. 대화 기록이 이를 희석시키는 것을 방지할 수 있습니다.

간체와 번체 출력 제어

문자 선택은 모델 설정이 아닌 사용자 로케일에 기반한 제품 결정 사항입니다. 중국 본토 대상 제품은 간체자를 기대하며, 대만과 홍콩 대상 제품은 번체자와 다른 어휘(일반적으로 소프트웨어, 네트워크, 데이터베이스 용어)를 기대합니다. 실용적인 접근법은 로케일 태그를 시스템 프롬프트에 매핑하고 코드에서 선택을 명시하는 것입니다.

• zh-CN, zh-SG: 간체, 중국 본토 어휘, 반각 숫자, 전각 중국어 구두점.
• zh-TW: 번체, 대만 어휘, 인용문에는 꺾쇠 괄호가 흔히 사용됩니다.
• zh-HK: 번체 및 홍콩 어휘; 제품에 고정된 용어가 있는 경우 짧은 어휘집을 제공하세요.

동일한 호출의 번체 버전은 다음과 같습니다. 시스템 프롬프트만 변경됩니다:

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)

모델은 가끔 다른 스크립트의 문자를 몇 개 누설할 수 있습니다. 특히 사용자 메시지가 다른 스크립트로 작성된 경우 더 자주 발생합니다. 경량화된 사후 확인을 추가하고, 문제가 발생하면 더 강력한 지시어로 한 번 더 재시도하세요. 샘플 확인을 넘어선 작업에는 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

대부분의 깨진 중국자 버그는 모델 문제가 아닙니다. 파이프라인의 어딘가에서 기본 인코딩 문제에서 비롯됩니다: 레거시 코드 페이지를 사용하는 Windows 콘솔, 인코딩 없이 열린 CSV, 콘텐츠 유형을 재작성하는 프록시 등. 모든 경계를 명시적으로 처리하세요.

Python에서는 encoding="utf-8"를 open에 전달하고, JSON을 직접 생성할 경우 ensure_ascii=False를 사용한 후 .encode("utf-8")를 호출하세요. 아래 예제는 plain requests로 수행하며, 호출의 원시 HTTP 구조도 보여줍니다:

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에서는 인코딩을 지정하지 않으면 readFile이 Buffer를 반환하며, 중국어가 포함된 템플릿 문자열은 소스 파일 자체가 UTF-8로 저장되어 있다면 문제가 없습니다. 공식 SDK는 본문을 자동으로 직렬화합니다:

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

더 두 가지 함정이 있습니다. 바이트 길이로 문자열을 자르면 문자가 반으로 잘릴 수 있으므로 항상 문자 단위로 슬라이스하세요. 그리고 스트리밍할 때는 멀티바이트 문자가 네트워크 청크로 나뉠 수 있으므로 스트림을 UTF-8로 증분 디코딩해야 합니다. SDK는 이를 처리하지만, 직접 작성한 파서는 그렇지 않은 경우가 많습니다.

중국어 텍스트 토큰 예산 책정

중국어에는 공백이 없으므로 단어 수는 예산 책정에 무의미합니다. 계획 가정치로, 측정된 상수가 아닌 것으로 간주하고, 중국어 문자 하나를 약 1~2 토큰으로 취급하며 단일 숫자가 필요할 때는 1.5를 사용하세요. 텍스트에 포함된 라틴어 단어와 숫자는 단어당 약 1.3 토큰에 가깝습니다. 이 비율은 어휘에 따라 다르므로 유일한 권위 있는 수치는 모든 응답과 함께 반환되는 usage 객체입니다.

작은 헬퍼 함수를 사용하면 요청 전에 프롬프트를 쉽게 추정하고 시간이 지남에 따라 실제 사용량에 따라 비율을 조정할 수 있습니다:

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

가정 사항을 명시한 계산 예시: 문자당 1.5 토큰의 2,000자 기사는 약 3,000 입력 토큰입니다. 400자 요약은 약 600 출력 토큰입니다. 입력 토큰 백만 개당 $0.25, 출력 토큰 백만 개당 $1.00일 때, 한 번 호출의 입력 비용은 약 $0.00075, 출력 비용은 약 $0.0006로 총 약 $0.00135입니다. 컨텍스트는 100,000 토큰으로 제한되므로, 동일한 가정 하에 약 40,000자의 프롬프트는 응답을 위한 여유 공간을 남깁니다.

긴 문서를 입력해야 할 때는 문장 중간이 아닌 문단 또는 제목 단위로 청킹하고, max_tokens을 명시적으로 설정하세요. 가격과 제한 사항은 가격 책정 페이지에 나열되어 있습니다.

멀티 턴 중국어 채팅을 창 안에 유지하기

채팅 기능은 매 요청마다 전체 대화 기록을 다시 전송하므로, 비용과 컨텍스트가 각 턴마다 증가합니다. 프롬프트와 완성 텍스트가 공유하는 컨텍스트 창이 100,000 토큰이므로, 긴 대화는 조치를 취하지 않으면 결국 400 오류를 발생시킵니다. 오류에 대응하기보다 초기에 정리 정책을 결정하세요.

간단한 정책은 시스템 프롬프트를 유지하고, 추정 프롬프트가 예산에 맞을 때까지 가장 오래된 턴을 제거한 후 나머지를 응답에 할당하는 것입니다. 아래 스케치 코드는 이전 섹션의 추정치를 재사용합니다:

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

튜터링 봇이나 지원 어시스턴트처럼 초기 컨텍스트가 중요한 제품의 경우, 제거된 턴을 완전히 버리는 대신 짧은 요약 메시지로 대체하세요. 모델에게 오래된 턴을 대화와 같은 문자로 몇 문장으로 압축하도록 요청한 후, 해당 요약을 시스템 프롬프트 바로 뒤에 삽입하세요. 이는 가끔 한 번의 추가 호출 비용이 들지만, 페르소나와 사실을 안정적으로 유지합니다.

채팅의 경우 max_tokens을 합리적으로 제한하는 것도 잊지 마세요. 메시징 UI의 응답은 보통 수백 토큰만 필요하며, 더 엄격한 제한은 지연 시간과 비용을 더 예측 가능하게 만듭니다. 응답을 토큰 단위로 스트리밍하면 체감 속도가 향상되며, 특히 사용자가 짧은 단위로 읽는 중국어 텍스트의 경우 더 효과적입니다.

출시 전 체크리스트 및 다음 단계

1. 각 로케일을 시스템 프롬프트로 매핑하고 매핑을 단위 테스트하세요.
2. 파일 읽기, 요청 본문 및 로그에 인코딩을 명시적으로 설정하세요.
3. 기능별로 usage을 로깅하고 매주 추정치와 비교하세요.
4. 402(no_credit), 429, 503(upstream_busy) 오류를 다르게 처리하세요: 충전, 요청 속도 줄이기, 몇 초 후 재시도.
5. 403 (content_blocked)은 재시도 대상이 아닌 해당 요청의 최종 응답으로 처리하세요.

앱에 번역 파이프라인이 포함되면 번역 및 현지화 가이드를 참조하세요. 연재 소설 및 캐릭터 채팅의 경우 웹 픽션 가이드를 확인하세요. 전체 파라미터 참조는 문서에 있습니다.