Chroma 的 collection 名带斜杠 建库直接报错

这类问题我又碰上了一次。chromadb 0.5 建集合时直接用文档路径当名字 docs/v2/faq，客户端抛 InvalidCollectionException，提示 name must be 3-63 characters and contain only alphanumeric characters。

第一反应是「名字长度超过 63 也会被拒」，验证下来不成立。

把日志和配置对完，能解释这个现象的基本就这几处。集合名只允许字母数字与下划线短横线；斜杠来自按目录建集合的写法；大小写与首尾符号另有约束。

先把所有候选名字打印出来核对合法性

python -c "import re;names=['docs/v2/faq','DOCS_V2_FAQ'];print([(n,bool(re.fullmatch(r'[A-Za-z0-9_-]{3,63}',n))) for n in names])"

再往下用路径哈希生成稳定且合法的名字

python -c "import hashlib;print('docs_'+hashlib.md5('docs/v2/faq'.encode()).hexdigest()[:8])"

建立路径到集合名的映射表并落盘

python build_alias.py --root docs/ --out alias.json

等前面都确认过，再用新名字重新建库并核对条数

python -c "import chromadb;print(chromadb.PersistentClient('db').get_or_create_collection('docs_1a2b3c4d').count())"

恢复的判定其实很直接。建集合不再抛异常，映射表里每条路径都有对应集合，导入条数与目录下的文档数一致。

容易忽略的是，用业务路径直接当集合名迟早会撞限制，加一层别名映射，后面换存储或改规则也容易。报错文案容易误导，真正的原因往往在相邻那一层的日志里。