ARTIFACT // CHECK-RAG-EMBEDDING-HEALTH.SH (SHELL)
本地 RAG 向量维度校验、双语余弦相似度与僵尸显存排查脚本 (check-rag-embedding-health.sh)
实测输出当前 Embedding 模型的精确向量维度（如 1024 vs 768），检查与对话模型共存时的显存驻留，并拦截空向量或维度冲突报错。
[核心实测结论 / TL;DR]本配置包「本地 RAG 向量维度校验、双语余弦相似度与僵尸显存排查脚本」（文件名：check-rag-embedding-health.sh，格式：SHELL）是 Tinker AI 实测工坊配套指南《embedding-dimension-mismatch-and-zombie-vram》的参数化生产模板。支持在本地浏览器实时定制 待检测向量模型 Tag (EMBED_MODEL=bge-m3:latest)、向量库期望维度数 (EXPECTED_DIM=1024)、Ollama 接口地址 (OLLAMA_ENDPOINT=http://127.0.0.1:11434) 等 3 项核心变量，默认遵循 127.0.0.1 回环绑定与最小权限规范。
04 // DIAGNOSISAPI 与部署排障· 验证日期：2026-10-26
查看全部 42 套配置附件 →check-rag-embedding-health.sh
查看配套实测指南 →本地 RAG 向量维度校验、双语余弦相似度与僵尸显存排查脚本
实测输出当前 Embedding 模型的精确向量维度（如 1024 vs 768），检查与对话模型共存时的显存驻留，并拦截空向量或维度冲突报错。
参数化定制变量 (Variables — 自动保存在本地浏览器)
UTF-8 编码 · 零延迟实时编译
#!/usr/bin/env bash
# Tinker AI — RAG Embedding Dimension & Multi-Model VRAM Healthcheck (Guide #20)
set -euo pipefail
EMBED="bge-m3:latest"
EXP_DIM="1024"
API="http://127.0.0.1:11434/api/embed"
echo "=== [1/3] Probing Vector Dimension for $EMBED ==="
RESP=$(curl -sS "$API" -d "{
\"model\": \"$EMBED\",
\"input\": [\"Tinker AI Lab bilingual RAG verification\", \"本地知识库跨语言向量检索测试\"],
\"keep_alive\": \"5m\"
}")
echo "$RESP" | python3 -c "
import sys, json, math
data = json.load(sys.stdin)
vecs = data.get('embeddings', [])
if not vecs:
print('[FAIL] Empty embeddings array returned! Check model tag.')
sys.exit(1)
dim = len(vecs[0])
exp = int('$EXP_DIM')
status = 'OK' if dim == exp else f'MISMATCH (Expected {exp}, Got {dim} -> Must re-index Vector DB!)'
dot = sum(a*b for a, b in zip(vecs[0], vecs[1]))
norm0 = math.sqrt(sum(a*a for a in vecs[0]))
norm1 = math.sqrt(sum(b*b for b in vecs[1]))
cos = dot / (norm0 * norm1) if (norm0 and norm1) else 0.0
print(f'Vector Dimension : {dim} [{status}]')
print(f'EN-ZH Cosine Sim : {cos:.4f} (Expect > 0.55 for multilingual models like bge-m3)')
"
echo "=== [2/3] Inspecting Co-Loaded Models & VRAM Split ==="
ollama ps
echo "=== [3/3] Checking OLLAMA_MAX_LOADED_MODELS Policy ==="
echo "Tip: Ensure OLLAMA_MAX_LOADED_MODELS>=2 so $EMBED and your Chat LLM do not thrash disk on every RAG query."
PARAMETER SPECIFICATION // 参数化变量规范说明表
「check-rag-embedding-health.sh」可定制环境变量与默认值说明
本配置模板（SHELL 格式）支持 3 项运行时参数注入，所有替换均在本地浏览器内完成。
| 模板占位符 | 参数用途说明 | 安全默认值 | 填写示例 |
|---|---|---|---|
{{EMBED_MODEL}} | 待检测向量模型 Tag | bge-m3:latest | bge-m3:latest | nomic-embed-text |
{{EXPECTED_DIM}} | 向量库期望维度数 | 1024 | 1024 (bge-m3) | 768 (nomic) | 384 (MiniLM) |
{{OLLAMA_ENDPOINT}} | Ollama 接口地址 | http://127.0.0.1:11434 | http://127.0.0.1:11434 |
PAIRED HARDWARE MANIFEST // 配套实测环境与边界记录
配套指南《本地 RAG 向量维度冲突 (1024 vs 768) 报错与显存“幽灵占用”深度排障指南》验证基线
实测硬件与操作系统 (Hardware & OS)
Linux / macOS / WSL2 · Ollama 0.5.7 · Open WebUI / Dify / Continue（ChromaDB, Qdrant, PGVector）
锁定软件栈与模型版本 (Pinned Versions)
Ollama 0.5.7bge-m3 (1024-dim)nomic-embed-text (768-dim)mxbai-embed-large (1024-dim)
离线与安全边界 (100% 本机向量库校验与显存进程诊断)
所有向量维度探测与 GPU 进程清理均在本地终端通过 `curl` 与 `nvidia-smi` 完成。
已知限制与失败边界 (Known Limits)
- 同维度不等于同向量空间！哪怕两个模型的输出维度完全相同（例如 `bge-m3` 与 `mxbai-embed-large` 均为 1024 维），用 A 模型建索引、切换 B 模型去检索，虽然不会报维度错误，但余弦相似度完全失效，召回结果等同于随机乱序！
- 更换 Embedding 模型后的唯一正确姿势：必须清空并重建对应知识库集合（Re-index Collection）。
DEPLOYMENT CHECKLIST // 配置落地核验步骤
部署 check-rag-embedding-health.sh 后的 3 步验收清单
- 已通过命令行实测确认当前 Embedding 模型输出维度（如 `bge-m3` 为 1024）与向量库集合维度完全一致。
- 在切换任何 Embedding 模型后，已清空旧向量集合并重新执行文档切片入库（Re-index）。
- 已设置 `OLLAMA_MAX_LOADED_MODELS=2`（或保持默认自动管理），防止 RAG 检索时向量模型与对话模型互相踢出显存。