fn-AI 模型 API (FnModelApi)

调用 fnOS 内置 AI 模型（img2vec 图像向量 / txt2vec 文本向量 / 人脸识别）的 HTTP API 服务。

• OpenAI 兼容嵌入接口 (/v1/embeddings)，支持文本 / 图片 / 混合输入，均输出 1024 维 向量
• 图片输入支持 base64 / NAS 本地路径 / 公网 URL（URL 需在面板开启并配置域名白名单，防 SSRF）
• 内置 API Key 认证、Origin 白名单、每模型 RPM 限流、远程图片 URL 白名单（管理面板 /config，仅桌面网关/本机可访问）
• 模型基于 fnOS AI Manager 的 OpenVINO IR 模型

快速开始：

1. 打开 release 页面 下载与你设备匹配的版本 通常选择x86即可，如果你是ARM设备，得再等等
2. 在 应用中心 左下角，选择 手动安装 上传fpk文件
3. 填写配置：
   • 服务端口: 通常端口保持默认即可
   • 磁盘槽位: 如果你的 AI模型 装在第一个盘 就写1，装在第二个盘 就写2，以此类推
4. 在桌面打开软件
   • 如果你的配置正常，则上方应显示 ✓ 已发现

   否则请去 设置 - 应用 - fn-AI 模型 API - 运行设置 修改你的信息

   • 下方模型应显示 ✓ 已就位，如果缺失模型，可以去 相册 安装模型（不安装只是缺失功能，不影响使用）

API文档

详细 API 文档见 app/server/README.md。

图文向量

此项目的 图文向量 使用标准 OpenAI 接口，可以直接接入其他程序

默认API地址：http://你的NAS地址:46091

模型名称：

• 文字向量：fn-txt2vec
• 图片向量：fn-img2vec

模型维度均为 1024

图片输入支持三种方式：

{"image": "<base64>"}                              // base64
{"image_path": "/vol3/1000/photo.jpg"}             // NAS 本机绝对路径
{"image_url": "https://cdn.example.com/photo.jpg"} // 公网 URL（需开启并配白名单）

/v1/embeddings 的 OpenAI 风格写法（Jina 风格 {"image": ...} 同样可用）：

{"input": [{"text": "一只猫"}, {"image_url": {"url": "https://cdn.example.com/cat.jpg"}}]}

远程 URL 默认关闭（防 SSRF）。需要用时在管理面板开启「远程图片 URL」并配置域名白名单，见下方说明。

人脸识别

此项目的 人脸识别 由于目前没有一个标准，默认使用自己的返回体

远程图片 URL（公网）

在管理面板（桌面入口「安全与限流设置」）开启后，image_url 字段可传公网图片 URL，由服务端下载后向量化。

• 默认关闭（防 SSRF）；开启后仅放行白名单内的公网 http/https 地址
• 内网/回环/链路本地/组播等保留地址一律拒绝（DNS 解析后校验），下载超时 10s、上限 20MB，重定向后的最终地址同样校验
• 白名单每行一个，支持三种写法：
  • cdn.example.com — 该域名及任意子域
  • *.example.com — 仅子域（不含裸域）
  • https://cdn.example.com/img/ — URL 前缀匹配
• 留空 = 不限制域名（仅限公网）

目录结构

app/server/         服务端（server.py + face_pipeline.py + API 文档）
app/ui/             桌面 iframe 网关配置
cmd/                启停脚本（cmd/main 为入口）
config/             fnOS 应用权限配置
wizard/             安装向导
manifest            fnOS 应用清单

自行编译

使用 fnpack 打包：fnpack build --directory .，产物 FnModelApi.fpk

鉴权

• 未配置 API Key 时所有端点放行
• 配置后调用 /api/* 与 /v1/* 需携带 Authorization: Bearer <key> 或 X-API-Key: <key>
• /health、/api/docs、/v1/models 豁免；/config* 仅桌面网关/回环可访问