Merge pull request #1 from zhangtaolab/dev

Dev

Author: forrestzhang

docs/faq/models_troubleshooting.md

@@ -1,3 +1,14 @@
 # Models Troubleshooting
 
-Please see [models](../user_guide/models.md) section for detailed usage, any troubleshooting not recorded will be added here.
+#### Mamba models on macOS (Apple Silicon)
+
+`mamba-ssm` relies on [Triton](https://github.com/triton-lang/triton), which only provides pre-built wheels for Linux. As a result, the `[mamba]` extra cannot be installed on macOS.
+
+**Workaround:** HuggingFace `transformers` includes a pure-PyTorch Mamba implementation (`MambaModel`) that works on macOS without `mamba-ssm`. To use it:
+
+```bash
+# Install without the [mamba] extra
+uv pip install -e '.[base,mcp,dev,notebook]'
+```
+
+Then load a Mamba model through `transformers` (cpu only) as usual. Note that this fallback path is significantly slower than the optimized `mamba-ssm` kernels (which require Linux + CUDA).