UnicodeEncodeError kapag nagpi-print ng LLM reply sa Python: 3 fix

Pumasa ang request mo, sumagot ang modelo, at pagkatapos namatay ang Python sa print(reply). Hindi kasalanan ng API. Maayos ang sagot; ang pinaglalagyan mo ng print ay hindi kayang i-represent ang ilan sa mga character nito. Ang pinakamabilis na fix ay i-on ang UTF-8 mode gamit ang PYTHONUTF8=1. Kung mas gusto mong panatilihin ito sa loob ng script, tawagin ang sys.stdout.reconfigure(encoding="utf-8") sa itaas, at kapag nagse-save ka ng sagot sa file, ipasa ang encoding="utf-8" sa open().

Ano ang hitsura ng error#

Sabihin nating nagtanong ka sa isang modelo sa Russian at ipi-print ang sagot. Ito ang buong script, gamit ang plain na requests call mula sa aming first-request guide:

import os, requests

r = requests.post(
    "https://api.cheaptokens.dev/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['CHEAPTOKENS_API_KEY']}"},
    json={
        "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
        "messages": [{"role": "user", "content": "Ответь одним предложением: что такое токен?"}],
        "max_tokens": 200,
    },
)
reply = r.json()["choices"][0]["message"]["content"]
print(reply)

Kapag ang stdout ay na-redirect sa isang file o pipe, o sinimulan ang Python gamit ang legacy code page para sa mga stream nito, ganito nagtatapos ang huling linya:

UnicodeEncodeError: 'charmap' codec can't encode characters in position 0-5: character maps to <undefined>

Ang pangalan ng codec sa iyong mensahe ay depende sa encoding ng stream (para sa Windows code page ito ay karaniwang charmap, para sa ascii ito ay ascii), at ang mga posisyon ay depende sa sagot. Palaging pareho ang hugis: ang traceback ay tumuturo sa print, hindi sa request.

Bakit nangyayari? Kino-convert ng print ang text sa bytes gamit ang encoding ng sys.stdout. Kung ang encoding na iyon ay isang legacy code page, anumang character na wala rito, tulad ng Cyrillic sa isang Western code page, isang emoji, kung minsan isang typographic dash, ay walang byte na mapagpapalitan. Nagra-raise ang Python sa halip na manghula.

Lumalabas ito sa tatlong sitwasyon:

• ang stdout ay na-redirect o naka-pipe (python app.py > out.txt, | another program), o tumatakbo ang script mula sa isang scheduler, CI o editor kung saan ang stdout ay hindi isang console;
• nakatakda ang PYTHONLEGACYWINDOWSSTDIO, o ang stream ay nakakakuha ng makitid na encoding;
• isinusulat mo ang sagot sa isang file gamit ang open(path, "w") at walang encoding=.

Aling Python? Ang lahat ng nasa ibaba ay tungkol sa Python 3.7–3.14, kung saan ang encoding ng stream at file ay nagmumula sa system. Ayon sa PEP 686 (status Final, https://peps.python.org/pep-0686/, checked 5 November 2026), ang UTF-8 mode ay naka-on bilang default mula sa Python 3.15, kaya ang open() at stdio ay gumagamit na ng UTF-8 doon maliban kung may nag-off nito gamit ang PYTHONUTF8=0 o -X utf8=0. I-check gamit ang python --version.

I-check kung anong encoding ang mayroon ka talaga#

Bago ka magbago ng kahit ano, tingnan kung ano ang pinili ng Python. Sampung segundo lang.

Gusto mong makita ang crash nang hindi naghihintay ng masamang araw? Sa macOS o Linux, pilitin ang makitid na encoding para sa isang run:

PYTHONIOENCODING=ascii python -c "print('Привет')"

Nabibigo iyon na may ascii codec message, kaparehong pamilya ng error sa itaas. Sa Windows, binabalewala ang variable para sa isang interactive console, ngunit gumagana ito kapag na-redirect ang output: sa cmd patakbuhin ang set PYTHONIOENCODING=ascii, pagkatapos python -c "print('Привет')" > out.txt (sa PowerShell: $env:PYTHONIOENCODING = "ascii").

Fix 1: i-on ang UTF-8 mode#

May mode ang Python na ginagawang default ang UTF-8 para sa text. Ayon sa Python docs (command-line page, checked 5 November 2026), binubuksan ito ng PYTHONUTF8=1 at pareho rin ang ginagawa ng -X utf8; parehong umiiral mula noong Python 3.7. Isang catch mula sa parehong page: anumang iba pang non-empty na value ng PYTHONUTF8 ay nagdudulot ng error sa startup, kaya gamitin nang eksakto ang 1 (o 0 para i-off ito). Sa 3.15, kailangan mo lang ito para tahasang i-enable ang mode sa mas lumang interpreters; kung naka-on na ito doon, hanapin ang PYTHONUTF8=0 sa iyong environment.

set PYTHONUTF8=1
python app.py

$env:PYTHONUTF8 = "1"
python app.py

PYTHONUTF8=1 python app.py

Walang pagbabago sa code, at saklaw nito ang console, redirects at files sa run na iyon. Kung ayaw mong mag-set ng variable bawat pagkakataon, pareho ang resulta ng python -X utf8 app.py mula sa command line.

Mayroon ding PYTHONIOENCODING=utf-8, na nag-o-override sa encoding ng stdin, stdout at stderr lamang. Basahin ang docs entry nito bago ka umasa rito sa Windows: mula noong Python 3.6, binabalewala ito para sa isang interactive console buffer maliban kung nakatakda ang PYTHONLEGACYWINDOWSSTDIO. Hindi apektado ng exception na iyon ang mga redirected file at pipe. Kaya maaayos nito ang python app.py > out.txt at wala pa ring gagawin sa console window. Para sa stderr, ang error handler ay palaging backslashreplace.

Fix 2: i-reconfigure ang stdout sa loob ng script#

Kung hindi mo makontrol kung paano sinisimulan ng mga tao ang script, baguhin ang stream mismo sa pinakataas:

import sys

sys.stdout.reconfigure(encoding="utf-8")
sys.stderr.reconfigure(encoding="utf-8")

print(reply)

Ang reconfigure ay dokumentado para sa io.TextIOWrapper (idinagdag noong 3.7). Kapag ipinasa mo ang encoding at iniwan ang errors, ang handler ay strict, kaya ang character na hindi kasya ay nagra-raise pa rin; para sa karaniwang kaso ng UTF-8, wala nang natitira. Dalawang detalye mula sa docs: hindi na mababago ang encoding kapag may nabasa nang data mula sa stream (pwede pagkatapos ng write), at sinusuportahan ang encoding="locale" mula noong 3.11.

Kailangan mong hindi kailanman mag-crash ang script, kahit sa terminal na talagang hindi kayang magpakita ng text? Idagdag ang errors="replace". Ang mga hindi kilalang character ay lalabas bilang ? sa halip na ihinto ang run. Itinatago nito ang problema sa halip na ayusin ito, kaya panatilihin ito para sa mga log.

Fix 3: bigyan ang mga file ng tahasang encoding#

Ang pag-save ng sagot ay parehong failure, mas tahimik lang sa code:

# before: on Python up to 3.14 this uses the system's default encoding
with open("reply.txt", "w") as f:
    f.write(reply)

# after: the file is UTF-8 on every machine
with open("reply.txt", "w", encoding="utf-8") as f:
    f.write(reply)

Gamitin ang parehong encoding="utf-8" kapag binabasa mo pabalik ang file, kung hindi, maaaring masira ang text sa pagpasok.

Aling fix ang dapat mong gamitin?#

Maaari mong pagsamahin ang mga ito. Ang script na nagpi-print at nagse-save ng mga sagot ay nangangailangan ng Fix 2 o Fix 1 para sa screen at Fix 3 para sa file.

Kung nabibigo pa rin#

• Lumipat ang error sa ibang linya. Kung gayon, ang nabibigong call ay isa pang print o write; kailangang maiapply ang fix bago ito tumakbo, kaya ilagay ang reconfigure sa pinakataas.
• Binabanggit ng error ang PYTHONUTF8. May value ang variable maliban sa 1 o 0. Alisin ito at i-set muli.
• Walang crash, pero may nakikita kang mga parisukat o ? sa console. Nagsulat ang Python ng valid na UTF-8; hindi ito maipakita ng console font o code page. I-redirect sa isang file at buksan ang file sa isang editor para kumpirmahin na buo ang sagot.
• Ang error ay JSONDecodeError, hindi UnicodeEncodeError. Ibang problema: tingnan ang paano mag-extract ng JSON mula sa sagot ng modelo.

Ang request code sa itaas ay ang plain na requests call; ang CheapTokens docs ay nagpapakita ng parehong call para sa OpenAI SDK. Gumagana ang isa pang modelo sa parehong fix: palitan ang model field ng zai-org/GLM-5.3-Flash (hanggang 8,192 output tokens bawat sagot, 390K context). Walang kinalaman ang encoding error sa modelo, sa kung saan napupunta ang text lang.