在 RAG 知识库项目中调试多租户 collection 命名问题，以下是完整排查过程。
用 f"{tenant_id}_{collection}" 给 Milvus collection 拼名字，tenant_id 是 UUID，拼出来的名字以数字开头、还含连字符 -，直接违反 Milvus 命名规则抛 code=1100。规则一句话：首字符必须是字母或下划线，只能含 [a-zA-Z0-9_]，禁止连字符。UUID 不能直接拼接，要么用原始 collection 名，要么转换成合法标识符。
在 RAG 知识库项目中调试混合检索评分问题，以下是完整排查过程。
Milvus 混合检索的加权融合分数 = 0.7 * dense_score + 0.3 * sparse_score，理论最大值约 0.7。如果用 min_similarity=0.7 过滤，结果几乎全被剔除。解决方案：将阈值降到 0.3，或根据融合策略动态调整。
在 RAG 知识库项目中调试查询结果返回格式问题，以下是完整排查过程。
RAG /query 接口返回的 sources 字段只包含 metadata，没有每条来源的 similarity 分数。解决方案：在组装响应时，将 metadatas 和 distances 合并，计算 similarity = 1 - distance。
在 RAG 知识库项目中调试混合检索评分问题，以下是完整排查过程。
Milvus 混合搜索（Dense + Sparse）有四个常见坑：空稀疏向量报错、Collection 未加载、sparse 格式错误、阈值过高。本文给出每个问题的最小修复代码。