> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/a-ghorbani/pocketpal-ai) · [上游 README](https://github.com/a-ghorbani/pocketpal-ai/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
PocketPal AI logo # PocketPal AI **一款完全在手机上运行的私人 AI 助手。** 与语言模型聊天、为它们赋予语音，并让它们使用工具 —— 全部在设备本地完成。无需账号、无需云端、无需联网。 pocketpal.dev · 获取应用 · 排行榜 · PalsHub · 讨论区
[![App Store](https://img.shields.io/badge/App_Store-Download-0D96F6?logo=apple&logoColor=white)](https://apps.apple.com/us/app/pocketpal-ai/id6502579498) [![Google Play](https://img.shields.io/badge/Google_Play-Get_it-414141?logo=googleplay&logoColor=white)](https://play.google.com/store/apps/details?id=com.pocketpalai) [![Latest release](https://img.shields.io/github/v/release/a-ghorbani/pocketpal-ai?sort=semver)](https://github.com/a-ghorbani/pocketpal-ai/releases) [![License: MIT](https://img.shields.io/github/license/a-ghorbani/pocketpal-ai)](LICENSE) [![Stars](https://img.shields.io/github/stars/a-ghorbani/pocketpal-ai)](https://github.com/a-ghorbani/pocketpal-ai/stargazers) [![Open issues](https://img.shields.io/github/issues/a-ghorbani/pocketpal-ai)](https://github.com/a-ghorbani/pocketpal-ai/issues) [![Sponsor](https://img.shields.io/github/sponsors/a-ghorbani?logo=githubsponsors)](https://github.com/sponsors/a-ghorbani)
--- ## 为什么选择 PocketPal AI？ 大多数 AI 应用只是别人服务器上的一层薄窗口 —— 你输入的每条消息都会被发送到你看不到的地方，被记录和分析。PocketPal 颠覆了这一模式：**AI 运行在你的手机上，你的对话永远不会离开设备。** - **🔒 默认私密** —— 每条提示词、回复和文档都保留在你的设备上。不会上传到外部服务器，也不会存储在外部服务器上。 - **✈️ 离线可用** —— 下载一次模型即可使用，无需连接网络，也无需账号。在飞机上、在徒步小径上，任何地方都行。 - **📱 在你已有的硬件上运行** —— 真正的语言模型、语音和工具，针对你手机的 CPU、GPU 和 NPU 进行优化，充分发挥硬件潜力。 - **🆓 免费且开源** —— 无需订阅，也没有需要解锁 AI 的「专业版」层级。采用 MIT 许可证，在开放环境中构建。 > **隐私说明：** 唯一会离开设备的数据，是你明确选择分享的内容 —— 基准测试结果（如果你选择加入排行榜）以及通过应用提交的反馈。 ## 目录 - [功能](#features) - [获取应用](#get-the-app) - [工作原理](#how-it-works) - [使用应用](#using-the-app) - [面向开发者](#for-developers) - [参与贡献](#contributing) - [路线图](#roadmap) - [社区与支持](#community--support) - [许可证](#license) ## 功能 - **🧠 设备端聊天** —— 完全离线运行 GGUF 语言模型（Gemma、Qwen、Phi、Llama 等）。 - **🗣️ 文本转语音（Text-to-speech）** —— 通过设备端神经 TTS（Kokoro 及其他引擎）为你的助手赋予语音，无需云端调用。 - **🎭 Pals** —— 创建个性化助手，拥有各自的模型、系统提示词和个性（Assistant 与 Roleplay 类型）。 - **🛍️ [PalsHub](https://palshub.ai/)**** —— 发现并安装社区 Pals，包括通过应用内结账购买的优质 Pals。 - **🛠️ Talents 与工具** —— 让能力强的 Pals 在工具调用循环中调用内置工具（计算器、日期/时间、富 HTML 渲染）。 - **📥 Hugging Face 集成** —— 直接从 HF Hub 搜索并下载 GGUF 模型（包括受限模型），使用你的访问令牌（access token）。 - **📊 基准测试** —— 测量 tokens/sec 和内存占用，并可选择在 [AI Phone Leaderboard](https://pocketpal.dev/leaderboard). 上进行对比。 - **⚡ 硬件加速** —— CPU、GPU（iOS 上的 Metal、Android 上的 OpenCL/Adreno）和 NPU（Qualcomm Hexagon）推理路径，并具备优雅降级。 - **🌍 本地化** —— 支持 11 种语言，适用于手机和平板，包括完整的 iPad 支持。 ## 获取应用 | 平台 | | | --- | --- | | **iOS / iPadOS** | [![Download on the App Store](https://img.shields.io/badge/App_Store-Download-0D96F6?logo=apple&logoColor=white)](https://apps.apple.com/us/app/pocketpal-ai/id6502579498) | | **Android** | [![Get it on Google Play](https://img.shields.io/badge/Google_Play-Get_it-414141?logo=googleplay&logoColor=white)](https://play.google.com/store/apps/details?id=com.pocketpalai) | **开启首次聊天的三个步骤：** 1. **安装** —— 从 App Store 或 Google Play 安装 PocketPal。 2. **下载模型** —— 点击菜单（☰）→ **Models**，选择适合你手机的模型并下载（或从 Hugging Face 添加一个）。 3. **加载并开始聊天** —— 就这么简单，你已在完全离线状态下运行 AI。 ## 工作原理 使用 PocketPal 无需了解这些 —— 但如果你好奇手机如何离线运行真正的 AI，这里是简要说明。 PocketPal 是一个四层技术栈，从芯片到聊天 UI 逐层构建。每一层各司其职，依赖方向严格自上而下 —— JS 应用与原生桥接层通信，桥接层与推理引擎通信，引擎面向硬件后端。
PocketPal AI on-device stack — UI & Tool Use → Bridging → Engine → Hardware
| 层级 | 运行内容 | | --- | --- | | **UI & Tool Use** | React Native 应用（UI 使用 React Native Paper，状态管理使用 MobX，聊天历史存储在 WatermelonDB）。**`AgentRunner`** 驱动每一轮聊天 —— 流式输出 token、在模型调用时调度 **Talents**（工具），并将结果反馈以进行后续推理。**Pals** 是可配置的角色；**PalsHub** 是应用内用于分享和购买 Pals 的市场。 | | **Bridging** | 将 JavaScript 连接到引擎的原生模块。[`llama.rn`](https://github.com/mybigday/llama.rn) 通过 JSI 桥接 LLM 推理；[`react-native-speech`](https://github.com/a-ghorbani/react-native-speech) 和 `onnxruntime-react-native` 桥接文本转语音。 | | **Engine** | 推理引擎。**llama.cpp** 以量化 **GGUF** 格式运行语言模型。**ONNX Runtime** 以 **ONNX** 格式运行 TTS 语音模型。 | | **Hardware** | 实际进行数学运算的地方。PocketPal 面向 **CPU**（通用降级方案）、**GPU**（iOS 上的 Metal、Android 上 Qualcomm Adreno 的 OpenCL）和 **NPU**（Qualcomm Hexagon）—— 在完整后端不可用时优雅降级，并卸载部分层。 | ## 使用应用
📥 下载并加载模型
1. 打开应用，点击 **Menu**（☰），然后进入 **Models**。 2. 从列表中选择一个模型并点击 **Download**，或点击 **+** 从 Hugging Face 或本地存储添加一个。 3. 在 Hugging Face 中搜索 GGUF 模型，选择适合你设备内存和存储的量化版本 —— 立即下载或稍后收藏。 4. 下载完成后，点击 **Load**（或使用聊天输入框左侧的 chevron 图标，直接从聊天界面加载）。 Download Models
💬 聊天
1. 确保已加载模型。 2. 打开 **Chat** 页面并开始对话。 3. 推理期间屏幕保持常亮，空闲时自动关闭。 4. 使用复制图标 **Copy** 复制完整回复，或长按某段文字仅复制该段。 5. 长按可 **Edit** 编辑你的任意消息 —— AI 会从你的修改处重新生成。点击 **retry** 获取全新回答，也可选择不同模型。 Chat
🎭 Pals 与 PalsHub
创建个性化助手： - **Assistant Pal** —— 选择默认模型，设置系统提示词（自行编写或让应用生成），并自定义聊天输入框颜色。 - **Roleplay Pal** —— 包含上述全部功能，另加地点、AI 角色及其他上下文参数。 在聊天页面使用 Pal 选择器切换角色（Persona）。在应用内浏览 **[PalsHub](https://palshub.ai/)****，发现社区 Pal，包括通过应用内购买（in-app checkout）获取的高级版（美国 iOS 和 Android）。 Assistant Pal

正在创建鸡尾酒配方助手

📊 为你的设备跑分
1. 打开 **Benchmark** 页面。 2. 运行性能测试，比较不同模型的速度与效率。 3. 查看 tokens/sec 和内存占用。 4. 可选：将结果分享到 [AI Phone Leaderboard](https://pocketpal.dev/leaderboard). Benchmark
🔑 设置 Hugging Face 令牌（用于受限模型）
1. 在你的 Hugging Face 账户中创建访问令牌（[文档](https://huggingface.co/docs/hub/en/security-tokens)). 2. 在 PocketPal 中，前往 **Settings → Set Token**，粘贴并保存。 Token setup
💌 发送反馈
前往 **App Info → "Sharing your thoughts"**，输入你的反馈——功能请求、建议，任何内容——然后提交。 Send feedback
## 面向开发者 PocketPal 是一个标准的 React Native 应用。如果你能构建 React Native 项目，你就能构建 PocketPal。 ### 前置要求 - **Node.js** — 版本固定在 [`.nvmrc`](.nvmrc)（当前为 `22.21.0`）；运行 `nvm use` 以匹配该版本。较旧的 Node 版本将无法通过 `engines` 检查。 - **Yarn 1 (Classic)** — `packageManager` 固定为 `yarn@1.22.22`。 - **Xcode** + **CocoaPods**，以及 **Ruby + Bundler**（用于 iOS / Fastlane 工具链）。 - **Android Studio** + Android SDK/NDK。 平台相关细节请参阅 [React Native 环境配置](https://reactnative.dev/docs/set-up-your-environment)。 ### 克隆、安装与运行 ```bash git clone https://github.com/a-ghorbani/pocketpal-ai cd pocketpal-ai nvm use # match the pinned Node version yarn install # install JS dependencies (cd ios && pod install) # iOS only yarn start # Metro bundler yarn ios # build + run on iOS simulator yarn android # build + run on Android emulator ``` 核心端侧聊天无需任何后端密钥；仅 PalsHub/认证相关功能需要额外配置。 > **原生代码变更规则：** 如果你修改了 `package.json`、某个原生模块、`ios/`、`android/`、Podfile 或 `build.gradle`，请重新运行 `pod install` 并在两个平台上重新构建——仅 JS 热重载无法应用原生变更。 ### 质量门禁 ```bash yarn lint # ESLint yarn typecheck # tsc --noEmit yarn test # Jest yarn l10n:validate # validate locale JSON (placeholders, integrity) ``` 在提交 PR 之前运行 `yarn lint && yarn typecheck && yarn test`。提交信息由 Commitlint（[Conventional Commits](https://www.conventionalcommits.org/))）通过 Husky 钩子进行校验。
仓库结构
``` src/ ├── screens/ # Chat, Models, Pals, Benchmark, Settings, About, … ├── components/ # Reusable UI ├── store/ # MobX stores (Model, ChatSession, Pal, TTS, HF, Benchmark, …) ├── services/ │ ├── agent/ # AgentRunner — the chat / tool loop │ ├── talents/ # Tool engines + registries │ ├── tts/ # TTS engines (kokoro, kitten, supertonic, system) │ ├── palshub/ # PalsHub marketplace integration │ └── downloads/ # Model download manager ├── database/ # WatermelonDB schema, models, migrations ├── repositories/ # Data-access layer over the DB ├── locales/ # i18n JSON + lazy loader (index.ts is the registry) └── hooks/ api/ theme/ utils/ config/ specs/ ```
技术栈
版本固定在 [`package.json`](package.json)；要点如下： | 领域 | 选择 | | --- | --- | | 框架 | React Native `0.82.1`，React `19.1.1`（New Architecture） | | 语言 | TypeScript `5.0.4` | | UI | React Native Paper `5.14.5`，React Navigation | | 状态 | MobX `6`（`mobx`、`mobx-react`、`mobx-persist-store`） | | 持久化 | WatermelonDB（聊天历史）、AsyncStorage（设置）、Keychain（密钥） | | LLM | `llama.rn` `0.12.4` → llama.cpp · GGUF | | TTS | `react-native-speech` `2.3.1` + `onnxruntime-react-native` `1.23.2` · ONNX | | 工具链 | Yarn 1 (Classic)、ESLint、Prettier、Jest、Husky + Commitlint |
扩展 PocketPal
**Talent** 是模型在对话过程中可调用的工具。引擎在 `TalentRegistry` 中注册，并以工具模式（tool schema）暴露给模型；`AgentRunner` 检测到调用后执行引擎，并将结果返回给下一轮对话。 | Talent | 引擎 | 功能 | | --- | --- | --- | | `calculate` | `CalculateEngine` | 算术 / 表达式求值 | | `datetime` | `DatetimeEngine` | 当前日期 / 时间 | | `render_html` | `RenderHtmlEngine` | 在聊天中渲染模型生成的 HTML | 适合首次贡献的方向： - 新增 **Talent** — 实现一个 `TalentEngine` 并在 `src/services/talents/` 中注册。 - 新增 **TTS 引擎** — 在 `src/services/tts/engines/` 下添加。 - 新增 **语言区域** — 在 `src/locales/` 中添加 JSON 文件（或在 [Weblate](https://hosted.weblate.org/projects/pocketpal-ai/)). 上翻译）。
## 参与贡献 欢迎贡献——错误报告、修复、功能、翻译和文档都有帮助。 1. Fork 并创建分支：`git checkout -b feature/your-feature-name` 2. 进行修改；在真机/模拟器上运行（`yarn ios` / `yarn android`）。如果涉及原生代码，请重新运行 `pod install` 并重新构建。 3. 本地门禁：`yarn lint && yarn typecheck && yarn test` 4. 使用 [Conventional Commits](https://www.conventionalcommits.org/): `git commit -m "feat: add new talent"` 规范提交。 5. 推送并开启 pull request。 请先阅读 [Contributing Guidelines](CONTRIBUTING.md) 和 [Code of Conduct](CODE_OF_CONDUCT.md)。想将 PocketPal 翻译成你的语言？欢迎加入 [Weblate](https://hosted.weblate.org/projects/pocketpal-ai/). ## 路线图 - **工具调用扩展** — 扩充 Talents 目录并深化 agentic 循环，让 Pal 能在端侧完成更多任务。 有想法或发现了 bug？[提交 issue](https://github.com/a-ghorbani/pocketpal-ai/issues/new/choose) 或发起 [discussion](https://github.com/a-ghorbani/pocketpal-ai/discussions). ## 社区与支持 - 💬 **问题与想法** — [GitHub Discussions](https://github.com/a-ghorbani/pocketpal-ai/discussions) - 🐛 **Bug 与功能请求** — [GitHub Issues](https://github.com/a-ghorbani/pocketpal-ai/issues/new/choose) - 🌐 **官网** — [pocketpal.dev](https://pocketpal.dev/) - ❤️ **支持开发** — PocketPal 免费且无广告；[赞助](https://github.com/sponsors/a-ghorbani) 有助于保持这一状态。 ## 许可证 根据 [MIT License](LICENSE) 授权。 ## 致谢 PocketPal AI 建立在开源社区的基础之上，包括： - **[llama.cpp](https://github.com/ggerganov/llama.cpp)** — 高效的端侧 LLM 推理。 - **[llama.rn](https://github.com/mybigday/llama.rn)** — 面向 React Native 的 llama.cpp 绑定。 - **[react-native-speech](https://github.com/a-ghorbani/react-native-speech)** — 为端侧语音提供支持的 React Native TTS 桥接。 - **[ONNX Runtime](https://onnxruntime.ai/)** — 为端侧 TTS 提供支持的跨平台推理引擎。 - **[React Native](https://reactnative.dev/)**, **[MobX](https://mobx.js.org/)**, **[React Native Paper](https://callstack.github.io/react-native-paper/)**, **[React Navigation](https://reactnavigation.org/)**, **[WatermelonDB](https://github.com/Nozbe/WatermelonDB)**, 以及许多其他使本项目成为可能的开源库。

用 ❤️ 为希望 AI 常驻手机的用户打造。
如果 PocketPal 对你有帮助，不妨点个 ⭐ —— 这能帮助更多人发现该项目。