模型流式输出怎样处理半个 UTF-8 字符

模型流式输出出现“半个 UTF-8 字符”时，真正需要修复的通常不是模型，而是接收层把任意网络片段直接转换成字符串。网络读取可能停在一个汉字的第 1 或第 2 个字节，SSE 事件也有自己的帧边界。正确做法是：先按协议解析事件，再在仍面对原始字节的那一层保留不完整尾部；不要把每一次 Read 都当成一个完整字符。

官方文档：https://developers.openai.com/api/docs/guides/streaming-responses

如果使用 OpenAI SDK，response.output_text.delta 的 delta 已经是文本事件，直接追加即可。本文讨论的是自定义 HTTP/SSE 适配层、代理或跨语言桥接仍拿到字节片段时，怎样把 UTF-8 边界处理干净。

先分清三种边界

流式链路里至少有三种边界：HTTP 读取边界、SSE 事件边界、UTF-8 字符边界。它们互相独立。一次读取可能包含半行，也可能包含多个事件；一个中文字符通常由多个 UTF-8 字节组成，也可能被拆到两次读取中。把读取结果直接写成字符串，遇到拆分点就可能先生成替换字符，后续字节再到达时已经无法恢复。

可以把职责画成三层：传输层只负责收集字节，协议层负责识别 SSE 的空行和 JSON 字段，文本层才负责把完整字节解码成 rune。这个顺序很重要，因为先解码再拼接会把暂时不完整的字节永久变成错误字符。

适合的模式是“保留尾部，再继续解码”

Go 字符串本质上可以保存任意字节，for range 会按 UTF-8 解码 rune，但它不适合直接跨多个独立字节片段维护状态。自定义适配层只需要保存当前片段末尾尚未组成完整 rune 的字节，下一次推送时把它放到新片段前面。

package streamtext

import (
    "fmt"
    "strings"
    "unicode/utf8"
)

// UTF8Carry 只负责把原始字节片段拼成完整 UTF-8 文本。
// 它不解析 SSE，也不判断 JSON；协议解析应在外层完成。
type UTF8Carry struct {
    pending []byte
}

// Push 输出当前能完整解码的文本，并保留不完整的尾部字节。
func (c *UTF8Carry) Push(fragment []byte) (string, error) {
    buf := make([]byte, 0, len(c.pending)+len(fragment))
    buf = append(buf, c.pending...)
    buf = append(buf, fragment...)

    var out strings.Builder
    for len(buf) > 0 {
        r, size := utf8.DecodeRune(buf)
        if r == utf8.RuneError && size == 1 {
            // FullRune 为 false 表示还缺字节，留给下一次 Push。
            if !utf8.FullRune(buf) {
                break
            }
            // 已经是完整但非法的序列，不能静默制造替换字符。
            return "", fmt.Errorf("invalid UTF-8 at byte prefix %x", buf[:1])
        }
        out.Write(buf[:size])
        buf = buf[size:]
    }

    c.pending = append(c.pending[:0], buf...)
    return out.String(), nil
}

// Flush 在流结束时检查是否留下半个字符，避免静默丢失尾部。
func (c *UTF8Carry) Flush() (string, error) {
    if len(c.pending) == 0 {
        return "", nil
    }
    if !utf8.Valid(c.pending) {
        return "", fmt.Errorf("incomplete UTF-8 tail %x", c.pending)
    }
    text := string(c.pending)
    c.pending = nil
    return text, nil
}

DecodeRune 返回的宽度是字节数；当返回单字节 RuneError 且 FullRune 为假时，说明当前缓冲区只是“不够长”，不是“内容一定错误”。这正是应该暂存的情况。相反，完整但非法的序列应立即报错，让上层决定丢弃、重连还是记录异常。

不要让协议解析和字符解码互相越权

如果自己处理 SSE，先识别事件帧，再从事件 JSON 中取文本字段。不要为了“快一点”在每次网络读取后直接调用 string(chunk)，也不要用字符串长度判断字符数：长度是字节数，中文和表情符号的宽度不同。

还有一个常见反例：SDK 已经把事件解码成 Go 字符串，调用方又把它转成字节后按“半个字符”拼接。此时边界问题已经在 SDK 内部处理，重复缓存只会增加延迟，甚至把正常的 Unicode 替换字符误判为传输故障。

流结束时要检查什么

正常结束应该满足两个条件：协议层收到完成事件，文本层的 pending 为空。如果完成事件已经到达但仍有尾部字节，说明上游截断或适配层漏了数据；如果只有错误事件，则应保留错误原因，不把残留字节拼成“看起来完整”的答案。

结论：把模式用在正确的边界上

“保留尾部，再继续解码”适合原始字节适配层，不是所有流式客户端的通用必选组件。使用 SDK 时，优先消费它提供的文本增量事件；只有在自建代理、SSE 解析器、跨语言桥接或二进制读取层仍面对字节片段时，才引入 UTF8Carry 这样的状态对象。

最后可以用四个问题做判断：我当前拿到的是字节还是文本？我是否先处理了协议帧？解码器是否保存了不完整尾部？流结束时是否检查了残留和错误？四个答案都清楚，半个 UTF-8 字符就不会再被误当成模型输出质量问题。

相关问题

模型返回的 delta 会不会天然按一个汉字切分？

不能假设按汉字、词或完整语义切分。消费端应依赖事件和文本解码契约，不要把网络片段当作语言单位。

为什么不能直接用 strings.Builder 拼接每次读取结果？

如果输入已经是完整字符串当然可以；问题在于原始字节被提前转换成字符串时，损坏已经发生，Builder 只能把错误结果继续拼起来。