埋在坑（2026-06-18 RAG 层搭建）

1. 境内服务器 HuggingFace 被墙

• 现象: huggingface.co 连接被 GFW 阻断，transformers/fastembed 模型下载和校验均超时
• 解决: os.environ["TRANSFORMERS_OFFLINE"] = "1" + local_files_only=True
• 前提: 模型文件须已下载到本地缓存。首次需要翻墙或从镜像站下载
• 替代: 使用 hf-mirror.com (环境变量 HF_ENDPOINT=https://hf-mirror.com)

2. fastembed ONNX 转换挂死

• fastembed 0.8.0 在首次加载 PyTorch 模型时会自动转换为 ONNX，这个转换过程挂死不输出任何日志
• 系统有 onnxruntime 1.26.0，但转换过程不明原因阻塞
• 解决: 弃用 fastembed，改用 transformers 直接加载 PyTorch 模型

3. BGE 模型缓存路径非标准

• 模型文件在 /home/ubuntu/.cache/huggingface/BAAI/bge-small-zh-v1.5/ (直接目录)
• HuggingFace Hub 标准路径是 ~/.cache/huggingface/hub/models--BAAI--bge-small-zh-v1.5/snapshots//
• 解决: 直接在 from_pretrained() 传本地路径，不走 Hub

4. psycopg2 写入 NUL 字符异常

• Python psycopg2 的 cursor.execute() 传入字符串含 NUL (\x00) 会抛 ValueError: A string literal cannot contain NUL (0x00) characters.
• 解决: 写入前 content.replace("\x00", "")

5. .env 文件密码被截断

• /home/ubuntu/.hermes/.env 中 DEEPSEEK_API_KEY 和 OPENROUTER_API_KEY 显示为 *** 或 f56904...f5e7(带省略号)
• 实际 key 被工具截断或遮蔽，无法直接读取
• 解决: 使用本地 BGE 模型做 embedding，不依赖外部 API key

6. DeepSeek embedding API 不可用

• DeepSeek 的 Embedding API (deepseek-embedding 模型) 需要独立 API key
• 当前 Hermes 通过 OpenRouter 访问 DeepSeek 模型，但 OpenRouter 的 embedding 端点也需要 key
• 解决: 使用本地 BGE-small-zh-v1.5 模型 (CPU, 512维, 33MB)

7. pip install 被系统保护 (PEP 668)

• pip3 install fastembed 失败: error: externally-managed-environment
• 解决: 加 --break-system-packages 参数