MacOS下Gunicorn多UvicornWorker更新ChromaDB索引报错问题

问题根源 #

MacOS的CoreFoundation框架不支持在fork进程后直接复用已初始化的资源。当使用Gunicorn的--preload选项时，主进程会先加载整个FastAPI应用（包括ChromaDB的初始化逻辑），再fork出多个子Worker进程。此时ChromaDB或其依赖库在预加载阶段已初始化了CoreFoundation相关组件，子进程继承这些资源后调用相关API就会触发报错：

"The process has forked and you cannot use this CoreFoundation functionality safely. You MUST exec()."

解决方案（保留--preload选项） #

1. 延迟ChromaDB资源初始化 #

避免在FastAPI应用启动时直接创建ChromaDB客户端或集合，改为在首次请求时懒加载，确保每个子Worker进程独立初始化资源：

from fastapi import FastAPI, Depends
import chromadb

app = FastAPI()
# 全局变量暂存客户端和集合，初始为None
_chroma_client = None
_chroma_collection = None

def get_chroma_collection():
    """依赖项：懒加载ChromaDB集合"""
    global _chroma_client, _chroma_collection
    if _chroma_client is None or _chroma_collection is None:
        _chroma_client = chromadb.PersistentClient(path="./chroma_db")
        _chroma_collection = _chroma_client.get_or_create_collection(name="docs")
    return _chroma_collection

@app.post("/update")
def update_index(collection=Depends(get_chroma_collection)):
    # 这里执行文档更新/上传逻辑
    collection.add(...)  # 替换为你的实际代码
    return {"status": "索引更新完成"}

2. 自定义Worker重置资源（可选增强） #

为确保每个子Worker启动后彻底重置ChromaDB相关状态，可自定义UvicornWorker：

from uvicorn.workers import UvicornWorker

class CustomUvicornWorker(UvicornWorker):
    def run(self):
        # 重置全局变量，强制子Worker重新初始化
        global _chroma_client, _chroma_collection
        _chroma_client = None
        _chroma_collection = None
        super().run()

启动Gunicorn时指定自定义Worker：

gunicorn main:app --workers 4 --worker-class=main.CustomUvicornWorker --preload

3. 升级ChromaDB依赖 #

部分旧版本ChromaDB的依赖库可能存在MacOS下fork兼容问题，升级到最新稳定版（pip install --upgrade chromadb），看是否已修复相关初始化逻辑的问题。

内容的提问来源于stack exchange，提问作者Avinash Raj