跨平台开发

Cactus Compute：本地化部署 LLM/VLM/TTS 的跨平台解决方案

在移动端与桌面端上，如何充分利用大模型的强大能力，同时兼顾离线运行与性能需求？Cactus Compute 为开发者提供了一套完整的跨平台 SDK，支持 Flutter、React Native 以及原生 C/C++，可轻松接入各种 GGUF 格式模型（如 Qwen、Gemma、Llama、DeepSeek 等），无缝运行 LLM、VLM、Embedding、TTS 等多种 AI 能力，并可按需降精度量化至 2-bit，以降低计算与内存开销。

本文将带你全面了解 Cactus Compute 的核心特性、安装与用法示例、性能表现，以及如何参与项目、选用推荐模型，助你快速构建具备本地 AI 推理与云端备份能力的下一代智能应用。

核心特性概览

「跨平台支持」：原生支持 Flutter 与 React Native，覆盖 iOS、Android 等多端。
「多模型兼容」：任何符合 GGUF 规范的模型均可加载，包括通用 LLM、视觉模型（VLM）、Embedding 模型、TTS 模型等。
「高效量化」：从 FP32 到 2-bit 各种精度可选，在性能与算力受限设备上尽量降低资源占用。
「智能降级」：支持多种运行模式——本地优先（localfirst）、远程优先（remotefirst）、纯云端（remote），遇到性能瓶颈或设备异常时可自动切换至云端推理。
「脚本化调用」：提供 MCP tool-calls，可在应用内快速集成提醒、图像检索、消息回复等常用功能模板。
「模板化对话」：内置 Jinja2 渲染支持，方便自定义聊天逻辑与多轮上下文管理。
「完善生态」：官方提供 Flutter、React、C++ 文档与示例仓库，入门即用；另有 Discord 社区实时交流。

安装与初始化

在 Flutter 中集成

「添加依赖」
打开项目根目录终端执行：
```
flutter pub add cactus
```


2. **初始化模型**

   ```dart
   import 'package:cactus/cactus.dart';

   // 异步初始化 LLM
   final lm = await CactusLM.init(
     modelUrl: 'huggingface/gguf/your-model.gguf',
     contextSize: 2048,             // 上下文长度
   );
   ```

---

### 在 React Native 中集成

1. **安装包**

   ```bash
   npm install cactus-react-native && npx pod-install
   ```
2. **初始化模型**

   ```typescript
   import { CactusLM } from 'cactus-react-native';

   const { lm, error } = await CactusLM.init({
     model: '/path/to/your-model.gguf',
     n_ctx: 2048,
   });
   ```

---

### 原生 C/C++ 集成

1. **克隆仓库并编译示例**

   ```bash
   git clone https://github.com/cactus-compute/cactus.git
   cd cactus
   chmod +x scripts/*.sh
   cd cpp
   ./build.sh          # 编译 C++ 库与示例
   ```
2. **运行示例程序**

   * 语言模型：`./cactus_llm`
   * 视觉模型：`./cactus_vlm`
   * Embedding：`./cactus_embed`
   * TTS：`./cactus_tts`

---

## 主要功能示例

### 文本补全（Text Completion）

> **Flutter 示例**
>
> ```dart
> final messages = [
>   ChatMessage(role: 'user', content: '你好，世界！'),
> ];
> final response = await lm.completion(
>   messages,
>   maxTokens: 100,
>   temperature: 0.7,
> );
> print(response.choices.first.text);
> ```

> **React Native 示例**
>
> ```typescript
> const messages = [{ role: 'user', content: 'Hello, world!' }];
> const params = { n_predict: 100, temperature: 0.7 };
> const response = await lm.completion(messages, params);
> console.log(response);
> ```

### 语义向量（Embedding）生成

> **Flutter 示例**
>
> ```dart
> final result = await lm.embedding('待转换文本');
> print(result.embeddings);
> ```

> **React Native 示例**
>
> ```typescript
> const text = '待转换文本';
> const result = await lm.embedding(text, { normalize: true });
> console.log(result);
> ```

### 视觉语言模型（VLM）推理

> **Flutter 示例**
>
> ```dart
> final vlm = await CactusVLM.init(
>   modelUrl: 'huggingface/gguf/vision-model.gguf',
>   mmprojUrl: 'huggingface/gguf/mmproj.gguf',
> );
> final resp = await vlm.completion(
>   [ChatMessage(role: 'user', content: '请描述这张图片')],
>   imagePaths: ['/absolute/path/to/photo.jpg'],
>   maxTokens: 200,
> );
> print(resp.choices.first.text);
> ```

---

## 云端降级与多模式策略

在移动设备上，网络不稳定、算力受限是常见问题。Cactus Compute 提供四种运行模式：

* **local**：纯本地运行，离线可用；
* **localfirst**：本地优先，失败时自动切换云端；
* **remotefirst**：优先云端，本地作为容灾；
* **remote**：全程云端，适合模型过大或设备算力不足时使用。

```dart
// Flutter 云端降级示例
final embedding = await lm.embedding(
  '示例文本',
  mode: 'localfirst',
);
```

---

## 性能表现一览

<img src="https://images.unsplash.com/photo-1511707171634-5f897ff02aa9?crop=entropy&auto=format&fit=crop&w=800&h=400" alt="手机性能" style="border-radius:20px; width:100%; margin:20px 0;">

下表展示了在常见旗舰机型上，Gemma3 1B 和 Qwen3 4B 模型的推理速度（Tokens/sec）：

| 设备                       | Gemma3 1B Q4 | Qwen3 4B Q4 |
| :----------------------- | :----------: | :---------: |
| iPhone 16 Pro Max        |      54      |      18     |
| iPhone 15 Pro            |      45      |      15     |
| OnePlus 13 5G            |      43      |      14     |
| Samsung Galaxy S24 Ultra |      42      |      14     |
| Xiaomi 13                |      24      |      8      |
| Redmi K70 Ultra          |      24      |      8      |
| …                        |       …      |      …      |

从结果可以看出，量化至 Q4 后模型在中高端机上均可实现数十 Tokens/sec 的实时对话能力，满足大多数移动端交互场景。

---

## 推荐模型与社区资源

* **官方 HuggingFace 模型库**：
  访问 [Cactus-Compute HuggingFace Page](https://huggingface.co/Cactus-Compute?sort_models=alphabetical#models) 查看项目维护团队推荐的各类模型。
* **Discord 社区**：
  加入我们的 Discord（[点击加入](https://discord.gg/bNurx3AXTJ)），与开发者、爱好者实时交流，获取最新示例与优化建议。
* **示例与文档**：

  * Flutter 文档：[GitHub Flutter 目录](https://github.com/cactus-compute/cactus/blob/main/flutter)
  * React 文档：[GitHub React 目录](https://github.com/cactus-compute/cactus/blob/main/react)
  * C++ 文档：[GitHub C++ 目录](https://github.com/cactus-compute/cactus/blob/main/cpp)

---

## 常见问题与建议

1. **模型加载缓慢？**

   * 检查文件路径与文件完整性，可尝试先行下载至本地存储，再通过绝对路径加载。
2. **运行时 OOM（内存不足）？**

   * 考虑将模型量化至更低位（如 Q4、Q2）或使用 `remotefirst` 模式进行云端推理。
3. **跨平台兼容性问题？**

   * 确保依赖版本与示例代码一致，必要时清理缓存并重装依赖（如 `flutter clean && flutter pub get`）。
4. **如何扩展自定义功能？**

   * 参考 MCP tool-calls 与 Jinja2 模板示例，结合业务需求灵活封装常用逻辑。

---

## 贡献与支持

如果你希望参与项目或提交功能/修复：

1. Fork 仓库并创建新分支：

   ```bash
   git checkout -b feature/your-feature
   ```
2. 实现并测试后，提交 PR。
3. 在 Issue 区先行讨论新功能或优化方案，以免重复劳作。

你的每一次贡献，都将助力更多开发者轻松构建高效 AI 应用！

---

## 总结与展望

Cactus Compute 致力于为跨平台开发者提供一套高性能、本地化兼容与云端降级并存的 AI SDK，让 LLM、VLM、Embedding、TTS 等能力在移动端与桌面端都能无缝触达。无论是对实时交互有严格延迟要求的场景，还是离线环境下的用户隐私保护需求，亦或是遇到算力瓶颈时的云端备份，都能通过灵活的模式切换与多精度量化，实现稳定可靠的 AI 服务。期待你在项目中实践并贡献更多思路，让 AI 推理真正“落地”到每一个应用中！

```markdown
![加入我们](https://images.pexels.com/photos/3184301/pexels-photo-3184301.jpeg)  
*图：与全球开发者一起，共同构建 AI 应用新生态*

跨平台本地部署LLM神器！Cactus Compute如何让Flutter/React Native秒接AI能力？

Cactus Compute：本地化部署 LLM/VLM/TTS 的跨平台解决方案

目录

核心特性概览

安装与初始化

在 Flutter 中集成

相关文章