踩坑记录

1. UnicodeEncodeError: 'ascii' codec can't encode characters in position 7-8

现象：运行 01_hello_llm.py 时报这个错误。

原因：API Key 里混进了中文。HTTP 请求头只能包含 ASCII 字符，鉴权头格式是 Bearer <Key>，而 Bearer （含空格）正好 7 个字符，所以第 7、8 位就是 Key 的头两个字——说明 .env 里还留着中文占位符"你的key"。

解决：把那一行改成平台给的真实 Key，例如：

LLM_API_KEY=<redacted>

不要加引号，不要留中文或空格。

2. token 统计偏低 / 不随历史增长

现象：多轮聊天中，第二轮的 prompt_tokens 明显小于"上一轮输入 + 上一轮输出"。

分析：代码本身没问题（模型仍记得前文）。最可能的原因是中转平台的计费口径不同，例如已缓存的历史（上下文缓存命中）没有计入 prompt_tokens，或只报告了新增部分。

结论：这是平台统计方式的问题，不影响学习，可以跳过。如想深究，可打印 resp.usage.model_dump() 查看是否有 cached_tokens 之类的字段。

3. 扫描版 PDF：每页 0 字

现象：一份 163 页的 PDF，用 pypdf 读出来每页都是 0 字。

原因：这是扫描版 PDF，每页都是图片，没有文字层，必须先做 OCR（文字识别）。

先检查：check_pdf.py

from pypdf import PdfReader

reader = PdfReader("data/你的文件.pdf")
total = len(reader.pages)
print("总页数：", total)

# 抽查几页的字数；注意页码不能超过总页数，否则会报错
for i in [0, 1, total // 2, total - 1]:
    text = reader.pages[i].extract_text() or ""
    print(f"第 {i + 1} 页：{len(text)} 字")

OCR 处理：用 RapidOCR（本地运行，中文效果好）

pip install rapidocr_onnxruntime pymupdf

ocr_pdf.py：

import fitz                                  # pymupdf：把 PDF 每页渲染成图片
from rapidocr_onnxruntime import RapidOCR    # 本地 OCR 引擎

engine = RapidOCR()
pdf = fitz.open("data/你的文件.pdf")

with open("data/你的文件.txt", "w", encoding="utf-8") as f:
    for i, page in enumerate(pdf):
        # 以 200dpi 渲染当前页，转成 PNG 字节，分辨率太低会影响识别率
        img = page.get_pixmap(dpi=200).tobytes("png")
        result, _ = engine(img)              # result：[[框坐标, 文字, 置信度], ...]，没识别到时为 None
        lines = [r[1] for r in result] if result else []
        f.write(f"=== 第 {i + 1} 页 ===\n")   # 标注页码，方便回答时追溯出处
        f.write("\n".join(lines) + "\n")
        print(f"第 {i + 1} 页完成，识别 {len(lines)} 行")

识别完成后，把原 PDF 移出 data/，只留 txt，删除 kb_storage 后重建索引。

4. 缺少 llama-index-readers-file：PDF 被当纯文本读

现象：读进来的内容以 %PDF-1.5 开头，全是二进制乱码；161 万字符被切成 2048 段，建索引要好几分钟，检索结果全是垃圾。

原因：没装 llama-index-readers-file，SimpleDirectoryReader 不认识 PDF，只能按纯文本读。

解决：

pip install llama-index-readers-file

然后删除旧索引再重建：

Remove-Item -Recurse -Force kb_storage

要点

换文档后也必须删除旧的 kb_storage，否则程序仍然加载旧索引。RAG 效果差，常常源于文档解析，而不是模型。