mirrors/a-ghorbani--pocketpal-ai

Fork 0

Files

T

wehub-resource-sync c81ae3d2ea docs: make Chinese README the default

2026-07-13 10:12:31 +00:00

17 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

PocketPal AI

一款完全在手机上运行的私人 AI 助手。

与语言模型聊天、为它们赋予语音，并让它们使用工具 —— 全部在设备本地完成。无需账号、无需云端、无需联网。

pocketpal.dev · 获取应用 · 排行榜 · PalsHub · 讨论区

为什么选择 PocketPal AI？

大多数 AI 应用只是别人服务器上的一层薄窗口 —— 你输入的每条消息都会被发送到你看不到的地方，被记录和分析。PocketPal 颠覆了这一模式：AI 运行在你的手机上，你的对话永远不会离开设备。

🔒 默认私密 —— 每条提示词、回复和文档都保留在你的设备上。不会上传到外部服务器，也不会存储在外部服务器上。
✈️ 离线可用 —— 下载一次模型即可使用，无需连接网络，也无需账号。在飞机上、在徒步小径上，任何地方都行。
📱 在你已有的硬件上运行 —— 真正的语言模型、语音和工具，针对你手机的 CPU、GPU 和 NPU 进行优化，充分发挥硬件潜力。
🆓 免费且开源 —— 无需订阅，也没有需要解锁 AI 的「专业版」层级。采用 MIT 许可证，在开放环境中构建。

隐私说明： 唯一会离开设备的数据，是你明确选择分享的内容 —— 基准测试结果（如果你选择加入排行榜）以及通过应用提交的反馈。

功能

🧠 设备端聊天 —— 完全离线运行 GGUF 语言模型（Gemma、Qwen、Phi、Llama 等）。
🗣️ 文本转语音（Text-to-speech） —— 通过设备端神经 TTS（Kokoro 及其他引擎）为你的助手赋予语音，无需云端调用。
🎭 Pals —— 创建个性化助手，拥有各自的模型、系统提示词和个性（Assistant 与 Roleplay 类型）。
🛍️ PalsHub** —— 发现并安装社区 Pals，包括通过应用内结账购买的优质 Pals。
🛠️ Talents 与工具 —— 让能力强的 Pals 在工具调用循环中调用内置工具（计算器、日期/时间、富 HTML 渲染）。
📥 Hugging Face 集成 —— 直接从 HF Hub 搜索并下载 GGUF 模型（包括受限模型），使用你的访问令牌（access token）。
📊 基准测试 —— 测量 tokens/sec 和内存占用，并可选择在 AI Phone Leaderboard. 上进行对比。
⚡ 硬件加速 —— CPU、GPU（iOS 上的 Metal、Android 上的 OpenCL/Adreno）和 NPU（Qualcomm Hexagon）推理路径，并具备优雅降级。
🌍 本地化 —— 支持 11 种语言，适用于手机和平板，包括完整的 iPad 支持。

获取应用

平台
iOS / iPadOS
Android

开启首次聊天的三个步骤：

安装 —— 从 App Store 或 Google Play 安装 PocketPal。
下载模型 —— 点击菜单（☰）→ Models，选择适合你手机的模型并下载（或从 Hugging Face 添加一个）。
加载并开始聊天 —— 就这么简单，你已在完全离线状态下运行 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` 通过 JSI 桥接 LLM 推理；`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）—— 在完整后端不可用时优雅降级，并卸载部分层。

使用应用

📥 下载并加载模型

打开应用，点击 Menu（☰），然后进入 Models。
从列表中选择一个模型并点击 Download，或点击 + 从 Hugging Face 或本地存储添加一个。
在 Hugging Face 中搜索 GGUF 模型，选择适合你设备内存和存储的量化版本 —— 立即下载或稍后收藏。
下载完成后，点击 Load（或使用聊天输入框左侧的 chevron 图标，直接从聊天界面加载）。

💬 聊天

确保已加载模型。
打开 Chat 页面并开始对话。
推理期间屏幕保持常亮，空闲时自动关闭。
使用复制图标 Copy 复制完整回复，或长按某段文字仅复制该段。
长按可 Edit 编辑你的任意消息 —— AI 会从你的修改处重新生成。点击 retry 获取全新回答，也可选择不同模型。

🎭 Pals 与 PalsHub

创建个性化助手：

Assistant Pal —— 选择默认模型，设置系统提示词（自行编写或让应用生成），并自定义聊天输入框颜色。
Roleplay Pal —— 包含上述全部功能，另加地点、AI 角色及其他上下文参数。

在聊天页面使用 Pal 选择器切换角色（Persona）。在应用内浏览 **PalsHub****，发现社区 Pal，包括通过应用内购买（in-app checkout）获取的高级版（美国 iOS 和 Android）。

正在创建鸡尾酒配方助手

📊 为你的设备跑分

打开 Benchmark 页面。
运行性能测试，比较不同模型的速度与效率。
查看 tokens/sec 和内存占用。
可选：将结果分享到 AI Phone Leaderboard.

🔑 设置 Hugging Face 令牌（用于受限模型）

在你的 Hugging Face 账户中创建访问令牌（文档).
在 PocketPal 中，前往 Settings → Set Token，粘贴并保存。

💌 发送反馈

前往 App Info → "Sharing your thoughts"，输入你的反馈——功能请求、建议，任何内容——然后提交。

面向开发者

PocketPal 是一个标准的 React Native 应用。如果你能构建 React Native 项目，你就能构建 PocketPal。

前置要求

Node.js — 版本固定在 .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 环境配置。

克隆、安装与运行

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 热重载无法应用原生变更。

质量门禁

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)）通过 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；要点如下：

领域	选择
框架	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). 上翻译）。

参与贡献

欢迎贡献——错误报告、修复、功能、翻译和文档都有帮助。

Fork 并创建分支：git checkout -b feature/your-feature-name
进行修改；在真机/模拟器上运行（yarn ios / yarn android）。如果涉及原生代码，请重新运行 pod install 并重新构建。
本地门禁：yarn lint && yarn typecheck && yarn test
使用 Conventional Commits: git commit -m "feat: add new talent" 规范提交。
推送并开启 pull request。

请先阅读 Contributing Guidelines 和 Code of Conduct。想将 PocketPal 翻译成你的语言？欢迎加入 Weblate.

路线图

工具调用扩展 — 扩充 Talents 目录并深化 agentic 循环，让 Pal 能在端侧完成更多任务。

有想法或发现了 bug？提交 issue 或发起 discussion.

社区与支持

💬 问题与想法 — GitHub Discussions
🐛 Bug 与功能请求 — GitHub Issues
🌐 官网 — pocketpal.dev
❤️ 支持开发 — PocketPal 免费且无广告；赞助有助于保持这一状态。

许可证

根据 MIT License 授权。

致谢

PocketPal AI 建立在开源社区的基础之上，包括：

llama.cpp — 高效的端侧 LLM 推理。
llama.rn — 面向 React Native 的 llama.cpp 绑定。
react-native-speech — 为端侧语音提供支持的 React Native TTS 桥接。
ONNX Runtime — 为端侧 TTS 提供支持的跨平台推理引擎。
React Native, MobX, React Native Paper, React Navigation, WatermelonDB, 以及许多其他使本项目成为可能的开源库。

用 ❤️ 为希望 AI 常驻手机的用户打造。

_{如果 PocketPal 对你有帮助，不妨点个 ⭐ —— 这能帮助更多人发现该项目。}

17 KiB Raw Permalink Blame History Unescape Escape