故障排查

常见问题的快速解决方案。

MCP 连接

Claude 中未显示工具

  1. 检查配置文件路径：

    • macOS：~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows：%APPDATA%\Claude\claude_desktop_config.json

    • Linux：~/.config/Claude/claude_desktop_config.json

  2. 检查 JSON 语法（逗号、括号是否缺失）

  3. 配置修改后重启 Claude

  4. 测试服务器：

    python -m chatspatial server --help

数据加载

“未找到数据集”

使用绝对路径：

❌ ~/data/sample.h5ad
❌ ./data/sample.h5ad
✅ /Users/yourname/data/sample.h5ad

文件格式无法识别

  • **H5AD：**用 python -c "import scanpy as sc; sc.read_h5ad('file.h5ad')" 验证

  • **Visium：**指向包含 spatial/ 文件夹的目录

  • 检查文件：file yourdata.h5ad 应显示 “HDF5”

分析错误

“请先运行预处理”

大多数分析都需要预处理。对 Claude 这样说：

"Preprocess the data"

“没有显著结果”

  • 检查数据质量（>500 个 spot、>1000 个基因）

  • 放宽显著性阈值

  • 尝试不同方法

细胞通讯分析失败

For mouse: species="mouse", liana_resource="mouseconsensus"
For human: species="human", liana_resource="consensus"

内存问题

系统卡死 / MemoryError

  • 先对数据做子采样用于测试

  • 使用更小的 batch size

  • 用 top 命令监控

  • 对大数据集：使用 32GB+ 内存或云端资源

CUDA 显存不足

  • 设置 use_gpu=False

  • 减小 batch size

  • 运行 torch.cuda.empty_cache()

快速修复

问题

解决方案

导入错误

uv pip install --upgrade chatspatial[full]

resolution-too-deep

Use uv instead of pip

Claude 无法连接

重启 Claude，检查 JSON 配置

路径错误

使用绝对路径

分析失败

先运行预处理

R 方法失败

安装 R 及其依赖包

获取帮助

下一步