---
title: Hailey专属AI Agent
emoji: 📚
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 6.29.1
python_version: "3.12"
app_file: app.py
pinned: false
short_description: Claude 与 DeepSeek、联网搜索及多格式文档问答
startup_duration_timeout: 30m
---

# Hailey专属AI Agent

Hugging Face Gradio Space，通过 **OpenRouter** 调用 Claude 与 DeepSeek。支持中文多轮聊天、流式输出、联网搜索和文档/图片上传，无需下载模型权重。

## 支持的模型

为缩短首屏加载时间，界面不再请求 OpenRouter 模型目录，也不显示价格面板。每次调用后仍会显示 OpenRouter 实际返回的 token 用量和费用；未返回费用时提示到 Activity 查看。

当前配置的参考价格（美元 / 每百万 tokens）：

| 模型 ID | 输入 | 输出 |
|---|---:|---:|
| `anthropic/claude-opus-5.5` | $4 | $20 |
| `anthropic/claude-sonnet-5.5` | $2 | $10 |
| `anthropic/claude-fable-5.1` | $10 | $50 |
| `deepseek/deepseek-v4.1-flash` | $0.30 | $1.20 |

默认 Sonnet 5.5，切换时保留会话上下文。仅调用所选模型，不自动替换为另一模型。图片、PDF、搜索结果及历史消息均计入输入；推理 tokens 计入输出。供应商、缓存及额外工具费用可能影响实付；界面显示 OpenRouter 返回的实际 `usage.cost`，未返回则提示到 Activity 查看。

## 默认联网

每次请求默认携带 `openrouter:web_search` server tool，由模型按需搜索；可取消勾选关闭。采用 `engine: native`，优先使用模型供应商原生搜索，供应商不支持时可能由 OpenRouter 回退到 Exa。原生搜索目录参考价为 **$0.01/次**；回退引擎按其当期价格结算。搜索结果处理的 tokens 另计。

使用新的 [Web Search Server Tool](https://openrouter.ai/docs/guides/features/server-tools/web-search)，不依赖已弃用的 `:online` 后缀。回答附带 API 返回的来源链接；开启搜索不等于每条消息都一定搜索。

## 文件支持

| 类别 | 扩展名 | 处理方式 |
|---|---|---|
| PDF | `.pdf` | Base64 文件交给 Claude 原生阅读，支持扫描页和图表 |
| WORD | `.DOC`, `.DOCX` | LibreOffice 转 PDF 后交给模型，保留页面、图片和表格 |
| POWERPOINT | `.PPT`, `.PPTX` | LibreOffice 转 PDF，按幻灯片页面阅读；不包含讲者备注、动画或隐藏页 |
| EXCEL | `.XLS`, `.XLSX`, `.CSV` | 按工作表、行号读取单元格文本；XLSX 保留公式，XLS 使用已保存的值 |
| IMAGES | `.PNG`, `.JPG`, `.JPEG`, `.WEBP`, `.GIF`, `.BMP`, `.TIF`, `.TIFF` | 单帧图片转 JPEG，最长边缩放至 2048px，发送视觉输入 |

Excel 不执行公式，不分析嵌入图表/图片；需要视觉分析时请另存为 PDF 或上传截图。多帧 GIF/TIFF 明确拒绝，避免只读首帧而遗漏内容。Office 转换可能改变字体、分页；对版式要求严格时建议直接上传原始 PDF。加密文件需先移除密码。

限制：每次最多 8 个文件；单文件 15 MB、单次合计 20 MB；每个会话最多 100 页 PDF（含 Office 转换结果）；每个表格最多扫描 10 万单元格、提取 25 万字符；单条提问 10 万字符；最多 40 轮；完整 API 请求最多 28 MB。超过限制会提示拆分或新建会话，不会静默截断内容。

## 部署到 Hugging Face

推荐创建 **私有 Space**，因为所有访客调用会消耗同一个 API Key 的余额。代码和运行中的应用均仅账号所有者及协作者可访问。

1. 安装当前 `hf` CLI 并登录：`hf auth login`。
2. 创建 Gradio Space，将本仓库上传。CPU Basic 足够，无需 GPU。当前 HF 对 CPU Gradio Space 的创建要求 PRO/Team 等计划；免费个人账号可在符合条件时使用 ZeroGPU。账号权益以 HF 实际响应为准。
3. 在 Space **Settings → Secrets** 添加 `OPENROUTER_API_KEY`。
4. 等待构建完成。`packages.txt` 安装 LibreOffice 和中文字体；`requirements.txt` 安装其他依赖。Gradio 由 README 的 `sdk_version` 控制。

也可用仓库内的部署脚本：

```bash
hf auth login
python3 scripts/deploy.py YOUR_USERNAME/claude-document-studio
```

脚本通过 `getpass` 安全读取 OpenRouter Key，再经标准输入传给 HF CLI。密钥不会写入文件、命令行参数或 Git。脚本默认私有 Space、CPU Basic，只上传明确列出的源文件。它不覆盖已有 Space，避免意外修改其他项目。若选用 ZeroGPU，请先阅读 HF 当前要求，并使用：

```bash
python3 scripts/deploy.py YOUR_USERNAME/claude-document-studio --hardware zero-a10g
```

ZeroGPU 模式通过环境变量 `USE_ZEROGPU=1` 加载兼容入口；正常聊天仍运行在 CPU，不占用 GPU。该模式需对应账号具备 ZeroGPU 创建资格。

公开 Space 前，请先在 Secrets 设置 `APP_PASSWORD`，并设置环境变量 `REQUIRE_APP_PASSWORD=1`。应用会先显示仅密码门禁，验证成功后才展示主界面。默认私有部署不额外要求应用密码。

## 本地运行

Python 3.12，安装 LibreOffice（macOS：`brew install --cask libreoffice`；Linux：安装 `packages.txt` 中软件包），确保 `soffice` 或 `libreoffice` 在 PATH 中。

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install 'gradio==6.29.1' -r requirements.txt
# 在终端安全输入，不把真实 Key 写入命令历史。
read -s -p 'OpenRouter API Key: ' OPENROUTER_API_KEY
export OPENROUTER_API_KEY
python app.py
```

打开 `http://localhost:7860`。应用不自动读取 `.env`，`.env.example` 仅说明环境变量名称。

## 数据与错误处理

API Key 只在服务器读取，浏览器不会收到。上传文件在 Space 临时目录中处理，文档内容发送至 OpenRouter 及模型供应商；搜索查询发送至搜索服务。无应用数据库或持久对话日志。Gradio 临时文件按小时清理；会话状态在一小时 TTL 后清理（Gradio 会话规则适用），Space 重启会丢失内存状态。

成功的一轮对话才写入上下文。停止/报错后保留输入以便重试，未完成的回复不写入后续上下文。取消无法保证撤销供应商已产生的费用。API 401/402/429、超时、空回复、文件损坏和超限均显示可读提示；不会在界面暴露上游原始错误、密钥或请求内容。不会自动重试可能已计费的请求。

## 文件结构

```text
app.py           Gradio 界面、会话管理与流式显示
router.py        模型配置、API 请求、引用和费用
attachments.py   PDF / Office / Excel / 图片处理
requirements.txt Python 依赖（Gradio 由平台管理）
packages.txt     系统依赖（LibreOffice、中文字体）
scripts/deploy.py 私有 Space 创建、Secret 配置与上传
scripts/smoke_remote.py 远程 Space 端到端验收（会产生少量 API 用量）
```

部署后的验收：确认 `RUNNING` 和启动日志；分别选择三个模型发送短消息；上传 PDF、DOCX、PPTX、XLSX 和图片各一份；追问附件内容；测试开启/关闭联网与来源显示；验证停止、新建对话和无效文件提示。仅语法检查不能代替这些线上验证。