安装指南

Ai管家 支持 macOS 11.0 (Big Sur) 及更高版本，专为 Apple Silicon (M1/M2/M3) 优化。

系统要求

项目	最低要求	推荐配置
macOS 版本	11.0 (Big Sur)	13.0 (Ventura) 或更高
处理器	Apple Silicon (M1/M2/M3)	M1 Pro/Max 或更高
内存	8 GB	16 GB 或更高
存储空间	500 MB（应用）	10 GB+（包含模型）

安装步骤

1. 下载安装包

访问我们的下载页面获取最新版本的 Ai管家。

2. 安装应用

1. 打开下载的 AiGuanjia_1.0.6_aarch64.dmg 文件
2. 将 Ai管家 图标拖拽到 Applications 文件夹
3. 等待复制完成

3. 首次启动

1. 在 Applications 文件夹中找到 Ai管家
2. 双击打开（首次启动可能需要右键选择"打开"）
3. 按照引导完成初始设置

Homebrew 安装

如果您使用 Homebrew，可以通过以下命令安装：

brew install --cask aiguanjia

快速开始

本指南将帮助您在 5 分钟内开始使用 Ai管家。

第一步：启动应用

打开 Ai管家 后，您会看到欢迎界面。点击"开始使用"进入主界面。

第二步：下载模型

1. 点击左侧导航栏的"发现"按钮
2. 浏览可用的模型列表
3. 选择适合您设备的模型（推荐从 7B 参数开始）
4. 点击"下载"按钮

第三步：开始对话

1. 下载完成后，点击左侧的"对话"按钮
2. 在输入框中输入您的问题
3. 按 Enter 或点击发送按钮
4. 等待模型响应

第四步：探索更多功能

• 概览面板 - 查看系统状态和模型信息
• 模型管理 - 管理已安装的模型
• 设置 - 自定义应用行为

提示：首次对话可能需要一些时间来加载模型，后续的响应会快很多。您可以使用"模型预热"功能来减少等待时间。

模型管理

Ai管家 提供了强大的模型管理功能，让您可以轻松管理本地 AI 模型。

支持的模型格式

• GGUF - llama.cpp 格式，最常用
• GGML - 旧版格式，仍然支持
• SafeTensors - HuggingFace 标准格式

导入本地模型

1. 打开"我的模型"页面
2. 点击"导入模型"按钮
3. 选择模型文件（.gguf 或 .bin）
4. 填写模型信息（名称、描述等）
5. 点击"确认导入"

模型变体

同一模型可能有多个量化版本，选择合适的版本可以平衡质量和性能：

量化级别	质量	速度	内存占用
Q4_K_M	良好	快	低
Q5_K_M	很好	较快	中
Q8_0	优秀	中等	高
F16	最佳	较慢	很高

对话功能

Ai管家 的对话界面设计简洁直观，同时提供了丰富的功能。

界面布局

• 侧边栏 - 显示对话历史列表
• 主区域 - 显示当前对话内容
• 输入框 - 底部输入区域，支持多行文本
• 工具栏 - 模型切换、设置等快捷操作

快捷键

快捷键	功能
Enter	发送消息
Shift + Enter	换行
Cmd + N	新建对话
Cmd + Shift + [	上一个对话
Cmd + Shift + ]	下一个对话

Markdown 支持

对话界面支持完整的 Markdown 渲染，包括：

• 标题、粗体、斜体
• 有序/无序列表
• 代码块（带语法高亮）
• 表格
• 引用块

本地 API

Ai管家 提供与 OpenAI 兼容的本地 API，让您可以将 AI 能力集成到自己的应用中。

启用 API

1. 打开 Ai管家 设置
2. 选择"API 服务器"标签
3. 勾选"启用本地 API"
4. 设置端口（默认 1234）
5. 保存设置

API 端点

Chat Completions

POST http://localhost:1234/v1/chat/completions
Content-Type: application/json

{
  "model": "local-model",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "max_tokens": 500
}

Models List

GET http://localhost:1234/v1/models

代码示例

Python

import openai

# Configure for local API
openai.api_base = "http://localhost:1234/v1"
openai.api_key = "not-needed"

# Create completion
response = openai.ChatCompletion.create(
    model="local-model",
    messages=[
        {"role": "user", "content": "What is machine learning?"}
    ]
)

print(response.choices[0].message.content)

JavaScript

const response = await fetch('http://localhost:1234/v1/chat/completions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'local-model',
    messages: [{ role: 'user', content: 'Hello!' }]
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

故障排除

遇到问题？这里列出了常见问题和解决方案。

模型加载失败

可能原因及解决方案

• 内存不足 - 尝试使用更小参数的模型或更高量化的版本
• 模型文件损坏 - 重新下载模型
• 不支持的格式 - 确保使用 GGUF 格式的模型

响应速度慢

• 启用"模型预热"功能
• 降低模型的量化级别（如从 Q8 改为 Q4）
• 关闭其他占用资源的应用程序
• 在设置中启用 GPU 加速

应用崩溃

1. 检查 macOS 是否为最新版本
2. 查看崩溃日志：~/Library/Logs/AiGuanjia/
3. 尝试重置应用设置
4. 在 GitHub Issues 上报告问题

常见问题

一般问题

Ai管家 是免费的吗？

是的，Ai管家 是完全免费的开源软件，采用 MIT 许可证。

支持 Intel Mac 吗？

目前 Ai管家 主要针对 Apple Silicon 优化。Intel Mac 可能可以运行，但性能会有所下降。

数据会发送到云端吗？

不会。Ai管家 完全在本地运行，所有数据和对话都不会离开您的设备。

模型相关问题

从哪里下载模型？

您可以通过 Ai管家 内置的"发现"功能浏览和下载模型，或从 HuggingFace 手动下载 GGUF 格式的模型。

模型存储在哪里？

模型默认存储在 ~/Library/Application Support/AiGuanjia/models/。

可以删除已下载的模型吗？

可以。在"我的模型"页面，右键点击模型选择"删除"，或点击模型详情页的删除按钮。

发现与下载

发现功能让您可以轻松浏览和下载来自 HuggingFace 的模型，无需离开应用即可完成模型的查找和安装。

浏览模型

打开"发现"页面，您可以：

• 搜索模型 - 通过关键词搜索特定的模型
• 分类筛选 - 按模型类型（聊天、代码、多语言等）筛选
• 排序 - 按下载量、评分、更新时间排序
• 查看详情 - 了解模型的参数、量化选项和性能特点

下载模型

1. 在发现页面找到想要的模型
2. 点击模型卡片进入详情页
3. 选择适合的量化版本（考虑您的内存限制）
4. 点击"下载"按钮
5. 等待下载完成，模型将自动添加到"我的模型"

推荐的模型来源

• TheBloke - 提供大量高质量的量化模型
• Qwen - 阿里巴巴的通义千问系列
• DeepSeek - DeepSeek AI 的模型系列
• Llama - Meta 的 Llama 系列模型

运行监控

实时监控功能让您可以全面了解模型的运行状态和系统资源使用情况，帮助您优化性能和排查问题。

监控指标

指标	说明
CPU 使用率	模型推理时的 CPU 占用情况
内存使用	已加载模型占用的系统内存
GPU 使用率	Apple Silicon GPU 的利用率
推理速度	每秒生成的 Token 数 (tokens/s)
上下文长度	当前对话使用的上下文长度

实时监控面板

在"运行监控"页面，您可以：

• 查看 CPU、内存、GPU 的实时使用率图表
• 监控当前加载模型的推理性能
• 查看历史资源使用趋势
• 设置资源使用警报阈值

性能优化建议

远程访问

远程访问功能允许您在其他设备（如 iPhone、iPad 或其他电脑）上使用 Ai管家 运行的模型，将您的 Mac 变成 AI 服务器。

启用远程访问

1. 打开 Ai管家 设置
2. 进入"远程访问"标签
3. 勾选"启用远程访问"
4. 设置访问端口（默认 8080）
5. 设置访问密码（强烈建议）
6. 保存设置

连接方式

Web 界面

在其他设备的浏览器中访问：

http://[您的Mac IP地址]:8080

API 调用

curl http://[您的Mac IP]:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [您的密码]" \
  -d '{
    "model": "local-model",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

使用场景

• 手机访问 - 在 iPhone 或 Android 上使用 Mac 运行的模型
• 团队协作 - 让局域网内的同事共享使用
• API 服务 - 为其他应用提供 AI 能力后端

批处理

批处理功能让您可以高效地一次性处理大量文本任务，比逐个处理更加高效和便捷。

使用场景

• 批量翻译 - 一次性翻译多个文档或段落
• 文本总结 - 批量生成文章摘要
• 数据标注 - 对大量数据进行分类或标注
• 内容生成 - 批量生成营销文案或产品描述

如何使用

1. 进入"批处理"页面
2. 选择要使用的模型
3. 输入系统提示词（可选）
4. 添加要处理的文本（支持批量粘贴或文件导入）
5. 点击"开始处理"
6. 等待处理完成，导出结果

支持的文件格式

格式	说明
TXT	纯文本文件，每行一个任务
CSV	包含多列数据的表格
JSON	结构化数据格式
JSONL	每行一个 JSON 对象

导出结果

处理完成后，您可以：

• 导出为 CSV 文件
• 导出为 JSON/JSONL 格式
• 直接复制到剪贴板
• 保存为 Markdown 文档

设置参考

Ai管家 提供丰富的设置选项，让您可以根据自己的需求定制应用行为。

通用设置

设置项	说明	默认值
启动时检查更新	应用启动时自动检查新版本	开启
开机自动启动	系统启动时自动运行 Ai管家	关闭
最小化到菜单栏	关闭窗口时最小化到菜单栏而非退出	开启
语言	界面显示语言	跟随系统

模型设置

设置项	说明	默认值
默认模型	启动时自动加载的模型	无
模型存储路径	模型文件的存储位置	~/Library/...
GPU 加速	使用 Apple Silicon GPU 加速推理	开启
上下文长度	默认的最大上下文长度	4096

对话设置

设置项	说明	默认值
Temperature	控制输出的随机性（0-2）	0.7
Top P	核采样参数	0.9
最大生成长度	单次回复的最大 Token 数	2048
自动保存对话	自动保存对话历史	开启

API 服务器设置

设置项	说明	默认值
启用 API	开启本地 API 服务器	关闭
端口	API 服务器监听端口	1234
CORS	允许跨域请求	开启

快捷键设置

您可以自定义以下快捷键：

• 新建对话
• 切换模型
• 清空上下文
• 复制最后回复
• 打开设置