安装指南

本文覆盖三种安装路径：Windows 源码运行（开发者 / 推荐）、Windows 一键安装（普通用户）、Docker Relay（仅部署交换所/中继）。Familiars 是 Windows-first 应用，以下以 Windows 为主；macOS 支持有限，详见文末。

一、前置要求

依赖	最低版本	说明
Python	3.10+	后端 bridge 及全部 AI 模型均运行在此进程
Node.js	18+	Electron 前端渲染 + Vite 开发服务器
npm	9+	随 Node.js 自带
Git	任意	克隆仓库
CUDA Toolkit	12.6（推荐）	本地 GPU 推理所需；无 GPU 也可纯 API 运行（mode0）
NVIDIA 驱动	≥535	配合 CUDA 12.6；`nvidia-smi` 可查
Visual C++ Redistributable	2015–2022	部分 Python 包（`hnswlib`、`insightface`）依赖

GPU 分级

Bridge 启动时通过 nvidia-smi 读取显卡显存，自动分为四个等级（源码：src/base/gpu_tier.py）：

等级	显存阈值	行为
`mode0`	无独显 / <1 GB	API-only：所有本地模型回退到云端 LLM；无 decider、无本地 rewriter
`tier4`	1–5 GB（默认 `FAMILIARS_TIER4_MAX_MB=5000`）	4-bit 量化 + 顺序加载模型（rewriter 用完驱逐再加载 reranker）；decider/memorizer 队列触发
`tier6`	5–7.5 GB（默认 `FAMILIARS_TIER6_MAX_MB=7500`）	rewriter+embedder+reranker 共载；允许语音通话（纯音频）；decider/memorizer bf16
`tier8`	≥7.5 GB	全功能：所有模型同时加载，最高精度

缓存文件为 workspace/gpu_tier.json。可通过环境变量覆盖：

FAMILIARS_GPU_TIER=tier6 — 手动指定等级（用于在高端卡上测试低等级回退路径）
FAMILIARS_TIER4_MAX_MB=5000 — 调整 tier4 上界（MiB）
FAMILIARS_TIER6_MAX_MB=7500 — 调整 tier6 上界（MiB）
FAMILIARS_GPU_TIER_FORCE_REDETECT=1 — 强制重新探测，忽略缓存

Apple Silicon 没有 nvidia-smi，默认解析为 mode0（API-only）。如需强制启用本地推理，可手动设置 FAMILIARS_GPU_TIER=tier4（MPS 后端），但性能和稳定性不保证。

二、源码运行（推荐）

2.1 克隆仓库

bash

git clone <repo-url> familiars
cd familiars

2.2 Python 虚拟环境

bash

# 创建虚拟环境
python -m venv .venv

# 激活（PowerShell）
.venv\Scripts\Activate.ps1

# 激活（CMD）
.venv\Scripts\activate.bat

# 激活（Git Bash / WSL）
source .venv/bin/activate

2.3 安装 Python 依赖

关键：PyTorch 必须从官方索引安装 CUDA 12.6 版本，否则 pip install torch 会从 PyPI 拉取 CPU 版本，导致本地 QLoRA 模型推理慢 10 倍以上。

bash

# Windows（CUDA 12.6）
pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cu126

# macOS（CPU / MPS）
pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cpu

国内网络慢？加镜像参数：-i https://pypi.tuna.tsinghua.edu.cn/simple（PyTorch 索引地址不变，镜像只加速 PyPI 侧包）。

requirements.txt 关键依赖一览

包	版本	用途
`torch`	2.9.0+cu126	PyTorch 核心（CUDA 12.6）
`torchvision`	0.24.0+cu126	视觉模型
`torchaudio`	2.9.0+cu126	音频处理
`transformers`	4.57.3	HuggingFace 模型加载
`sentence_transformers`	5.2.2	嵌入模型
`FlagEmbedding`	1.4.0	RAG 重排
`fastapi`	0.136.1	HTTP API 框架
`hypercorn[h2]`	≥0.16.0	HTTP/2 服务器
`onnxruntime`	1.28.0	ONNX 推理（背景去除等）
`openai`	2.36.0	LLM API 客户端
`httpx`	0.28.1	异步 HTTP 客户端
`apscheduler`	3.11.2	定时任务调度
`faster-whisper`	≥1.0.0	语音识别（ASR）
`playwright`	1.59.0	浏览器自动化
`pydantic-settings`	≥2.5.0	环境变量校验
`python-dotenv`	≥1.0.0	`.env` 加载
`cryptography`	45.0.5	敏感信息加密
`paddleocr`	3.5.0	OCR 文字识别
`insightface`	0.7.3	人脸检测（数字人）
`mediapipe`	0.10.35	面部/手势追踪

平台限定包（requirements.txt 已自动处理）：

Windows only：uiautomation、wcferry（WeChat RPC）、pycaw、comtypes、wmi、pywin32
macOS only：AppKit、Quartz（pyobjc）

2.4 安装 Playwright 浏览器

bash

playwright install chromium

2.5 配置 `.env`

复制 .env.example 为 .env（或在仓库根目录新建），必须填写以下字段：

必填环境变量

变量	类型	说明	示例
`BASE_URL`	string	OpenAI 兼容 API 端点	`https://api.familiars.cn/v1`
`API_KEY`	string	LLM 服务商 API 密钥	`sk-xxxxx`
`DEFAULT_MODEL`	string	默认对话模型名	`gpt-4o`

MANAGER_MODEL 默认值为 gpt-4o，用于管理者（agent 0）的高管摘要与 persona 进化，通常选择更强的模型。

可选模型配置

变量	默认值	说明
`MANAGER_MODEL`	`gpt-4o`	管理者专用模型
`MINI_MODEL`	`Qwen2.5-1.5B`	本地轻量模型（decider 等）
`FAST_MODEL`	空（回退到 `DEFAULT_MODEL`）	低延迟云端快速模型（草稿解析、快速分类）
`EMBEDDING_MODEL`	`BAAI/bge-m3`	嵌入模型（sentence-transformers 名称或 HuggingFace 路径）
`RERANKER_MODEL`	`BAAI/bge-reranker-v2-m3`	重排模型

运行时调优

变量	默认值	说明
`MAX_TURNS`	`50`	单次对话最大工具调用轮数
`TIMEOUT`	`300`	HTTP 请求超时（秒）
`DIALOGUE_EXPIRE_TIME`	`3600`	对话空闲过期时间（秒）
`SLIDE_WINDOW_SIZE`	`5`	滑动窗口上下文条数
`TOP_K`	`5`	RAG 检索返回条数

FAMILIARS_* 前缀环境变量

变量	默认值	说明
`FAMILIARS_TIER4_MAX_MB`	`5000`	GPU tier4 显存上界（MiB）
`FAMILIARS_TIER6_MAX_MB`	`7500`	GPU tier6 显存上界（MiB）
`FAMILIARS_GPU_TIER`	自动探测	强制指定 GPU 等级（`mode0`/`tier4`/`tier6`/`tier8`）
`FAMILIARS_GPU_TIER_FORCE_REDETECT`	`0`	设为 `1` 强制重新探测 GPU
`FAMILIARS_APPROVAL_DISABLED`	`0`	设为 `1` 关闭所有工具审批（慎用，仅限开发环境）
`FAMILIARS_DB_PATH`	`workspace/familiars.db`	SQLite 数据库路径（测试可用 `:memory:`）
`FAMILIARS_HTTP_INSECURE`	`0`	设为 `1` 回退到 HTTP + uvicorn（不走 HTTPS/2 + hypercorn）
`FAMILIARS_BROKER_ADVERTISE_URL`	空	Broker 联邦公网/LAN 基础 URL
`FAMILIARS_BROKER_BIND`	`127.0.0.1`	Bridge HTTP 绑定地址（`0.0.0.0` 暴露跨机器访问）
`FAMILIARS_FRAMEWORK_DOCS_TOPK`	—	框架文档 RAG 检索条数

RAG 调优

变量	默认值	说明
`RAG_DENSE_TOPK`	`20`	稠密召回候选数
`RAG_CHUNK_SIZE`	`800`	分块目标大小（字符）
`RAG_RERANK_MIN_SCORE`	`0.0`	重排最低分数阈值（0=保留全部）
`RAG_RRF_K`	`60`	Reciprocal Rank Fusion 常数
`RAG_MULTIQUERY_N`	`1`	本地 rewriter 查询变体数（1=单查询）

熔断器

变量	默认值	说明
`CB_FAILURE_THRESHOLD`	`5`	熔断前失败次数
`CB_RECOVERY_SECONDS`	`30.0`	熔断恢复尝试间隔（秒）
`LLM_MAX_RETRIES`	`3`	单次 LLM 调用最大重试次数
`LLM_GATE_DISABLED`	`false`	设为 `true` 关闭并发门控（无限制）

第三方服务（可选）

变量	说明
`HUGGING_FACE_API_KEY`	HuggingFace API 密钥
`UPDATE_URL`	OTA 更新 feed 基础 URL（空=禁用）
`UPDATE_CHECK_INTERVAL_HOURS`	更新检查间隔（默认 24 小时）

2.6 Electron 前端

bash

cd electron
npm install

主要前端依赖（electron/package.json）：

包	版本	用途
`vue`	^3.5.41	前端框架
`electron`	^30.0.0	桌面壳
`pinia`	^2.1.7	状态管理
`@vue-flow/core`	^1.48.2	图表可视化（recipe/flow 编辑器）
`axios`	^1.7.0	HTTP 客户端
`markdown-it`	^14.3.0	Markdown 渲染
`highlight.js`	^11.11.1	代码高亮
`mermaid`	^11.16.0	流程图渲染
`katex`	^0.17.0	数学公式渲染
`onnxruntime-web`	^1.26.0	浏览器端 ONNX 推理
`@ricky0123/vad-web`	^0.0.30	语音活动检测（VAD）
`electron-updater`	^6.8.9	OTA 自动更新

三、启动

方式 A：Electron 全栈开发模式（推荐）

bash

cd electron
npm run electron:dev

这会：

启动 Vite 开发服务器（http://localhost:5173）
等待 Vite 就绪后启动 Electron 窗口
Electron 自动 spawn Python bridge 子进程（.venv/Scripts/python -m src.bridge.run）
Bridge 服务地址：https://127.0.0.1:18711（hypercorn + HTTP/2 + 自签证书自动生成于 workspace/.bridge.crt）

方式 B：仅后端 Bridge（后端测试 / 无 GUI）

bash

.venv/Scripts/python -m src.bridge.run

⚠️ 不要使用 uvicorn src.bridge.app:app --reload —— 会丢失 HTTP/2 支持，且 reload 机制在 worker 线程上 race 初始化 CUDA，Windows WDDM 下直接崩溃。

方式 C：CLI 驱动（需先启动 bridge）

bash

python main.py agents list --pretty
python main.py chat stream --prompt "你好" --agent-id 1
python main.py todos create --title "买牛奶" --deadline 2026-07-05T18:00

CLI 认证通过 X-Bridge-Token 头，自动从 workspace/.bridge_token 读取。可用 --token 或环境变量 BRIDGE_TOKEN 覆盖。

四、Windows 一键安装（普通用户）

安装包制作方式（开发者视角）：

进入 electron/，运行 npm run electron:build（Vite 打包 renderer + electron-builder 产出 Windows NSIS 安装包）。
安装包默认把 Python 侧依赖打进 extraResources；首次启动自动生成 workspace/ 与 .env。
用户双击安装 → 首次启动引导填入 LLM API 端点（BASE_URL / API_KEY / 模型名）。

安装器配置（electron/package.json → build.nsis）：

oneClick: false — 非一键安装，允许选择目录
createDesktopShortcut: true — 创建桌面快捷方式
createStartMenuShortcut: true — 创建开始菜单快捷方式
发布 feed：https://api.familiars.cn/_app-updates/（electron-updater generic provider）

五、Docker Relay（仅部署交换所/中继）

如需自托管 Broker 交换所（relay）：

bash

cd deploy/relay/app
cp .env.example .env   # 填 DOMAIN / CLOUDFLARE_API_TOKEN 等
docker compose up -d

架构链路：Cloudflare → Caddy:443 (DNS-01 TLS) → relay:18712。

详见 deploy/relay/app/README.md。

六、macOS 说明

本仓库 Python 侧与 Electron 侧以 Windows 为主。部分文件存在 macOS 分支但功能落后：

文件	macOS 状态
`src/models/assistant.py`	有 macOS 分支
`src/utils/autorun.py`	有 macOS 分支（launchd）
`src/base/auth/device.py`	macOS 有真实实现（Keychain）；Windows 仅 hostname 指纹
`src/utils/daily_tools.py`	macOS 导入 `AppKit`/`Quartz`（条件导入）

macOS 安装时 PyTorch 用 CPU 索引：

bash

pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cpu

七、常见安装错误与解决

问题	原因 / 解决
`pip install` 报 `Could not find a version that satisfies the requirement torch==2.9.0+cu126`	没加 `--index-url https://download.pytorch.org/whl/cu126`，PyPI 上没有 `+cu126` 后缀的包
`AttributeError: _ARRAY_API not found`	`onnxruntime` 版本过低（<1.28）与 NumPy 2.x 不兼容；确保 `requirements.txt` 中 `onnxruntime==1.28.0`
`pip install` 非常慢	加国内镜像：`-i https://pypi.tuna.tsinghua.edu.cn/simple`（PyTorch 索引地址不变）
启动报 self-signed cert 不信任	Electron 自动信任 `workspace/.bridge.crt`；CLI / 浏览器手动信任一次即可
端口 18711 被占用	Bridge 自动调用 `pickFreePort()` 选新端口，写入 `workspace/.bridge.port`；CLI 自动读取该文件
`ModuleNotFoundError: No module named 'pydantic_settings'`	`pydantic-settings>=2.5.0` 未安装；`python-dotenv>=1.0.0` 同理
`nvcc not found` / CUDA 编译失败	安装 CUDA Toolkit 12.6 + 对应版本 NVIDIA 驱动；或改用预编译 wheel
`uiautomation` 安装失败（macOS）	`requirements.txt` 已用 `sys_platform == "win32"` 限定；macOS 不应尝试安装
首次启动很慢（1-2分钟）	正常——bridge 需预热 embedder（`bge-m3`）、rewriter、rembg 等模型，首次还需下载
双 bridge 实例冲突	Electron 有 single-instance lock（`app.requestSingleInstanceLock()`），第二次启动会自动聚焦已有窗口而非启动新实例
`torch` 用了 CPU 版本	检查 `pip show torch` 的 Version 字段是否含 `+cu126`；否则重新安装
`lunardate` 找不到	农历日期转换库，`requirements.txt` 已包含；如漏装请 `pip install lunardate==0.3.0`

八、启动后的文件结构

首次启动后 workspace/ 目录自动生成：

workspace/
├── .bridge_token          # Bridge 认证令牌（CLI 自动读取）
├── .bridge.port           # Bridge 实际端口（18711 被占时为非默认值）
├── .bridge.crt            # 自签 HTTPS 证书
├── .bridge.key            # 自签 HTTPS 私钥
├── .bridge.log            # Bridge 运行日志
├── .bridges.json          # Bridge 实例信息（PID + port）
├── familiars.db           # SQLite 主数据库
├── gpu_tier.json          # GPU 等级缓存
├── SECRET.json            # 加密敏感信息（令牌等）
├── .paths_aliases.json    # 路径迁移别名记录
├── AGENTS.md              # 项目级 Agent 规则
├── USER.md                # 用户画像（memory writer 滚动更新）
├── IDENTITY.md            # 身份定义
├── agents/
│   └── agent_<id>/        # 每个 agent 的独立目录
│       ├── dialogue_<n>/  # 对话树数据
│       └── reports/       # 日报/周报/月报/年报
├── manager/
│   ├── entries/           # 桌面壳图标资源
│   └── flows/             # 已安装的 flow 模板
└── rewriter/
    └── prompt.md          # 查询改写提示词

下一步：五分钟上手 →

安装指南 ​

一、前置要求 ​

GPU 分级 ​

二、源码运行（推荐） ​

2.1 克隆仓库 ​

2.2 Python 虚拟环境 ​

2.3 安装 Python 依赖 ​

requirements.txt 关键依赖一览 ​

2.4 安装 Playwright 浏览器 ​

2.5 配置 .env ​

必填环境变量 ​

可选模型配置 ​

运行时调优 ​

FAMILIARS_* 前缀环境变量 ​

RAG 调优 ​

熔断器 ​

第三方服务（可选） ​

2.6 Electron 前端 ​

三、启动 ​

方式 A：Electron 全栈开发模式（推荐） ​

方式 B：仅后端 Bridge（后端测试 / 无 GUI） ​

方式 C：CLI 驱动（需先启动 bridge） ​

四、Windows 一键安装（普通用户） ​

五、Docker Relay（仅部署交换所/中继） ​

六、macOS 说明 ​

七、常见安装错误与解决 ​

八、启动后的文件结构 ​

安装指南

一、前置要求

GPU 分级

二、源码运行（推荐）

2.1 克隆仓库

2.2 Python 虚拟环境

2.3 安装 Python 依赖

requirements.txt 关键依赖一览

2.4 安装 Playwright 浏览器

2.5 配置 `.env`

必填环境变量

可选模型配置

运行时调优

FAMILIARS_* 前缀环境变量

RAG 调优

熔断器

第三方服务（可选）

2.6 Electron 前端

三、启动

方式 A：Electron 全栈开发模式（推荐）

方式 B：仅后端 Bridge（后端测试 / 无 GUI）

方式 C：CLI 驱动（需先启动 bridge）

四、Windows 一键安装（普通用户）

五、Docker Relay（仅部署交换所/中继）

六、macOS 说明

七、常见安装错误与解决

八、启动后的文件结构