# AIimg

**Repository Path**: zdyumath/aiimg

## Basic Information

- **Project Name**: AIimg
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Model Workbench

一个本地多模型调试台，可在同一界面调用 OpenAI、Claude、DeepSeek、Qwen 等模型，并测试流式对话、图片理解、图片生成、多模型对比和知识库问答。

## 快速开始

需要 Python 3.11 或更高版本。

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
Copy-Item .env.example .env
```

编辑 `.env`，只填写需要使用的平台密钥，然后启动：

```powershell
.\scripts\workbench.ps1 start
```

Windows 命令提示符：

```bat
scripts\workbench.bat start
```

Linux / macOS：

```sh
chmod +x scripts/workbench.sh
./scripts/workbench.sh start
```

三种脚本均支持 `start`、`stop`、`restart` 和 `status`。Windows PowerShell 可通过 `-BindHost`、`-Port` 覆盖监听参数；Shell 可追加 `[host] [port]`。未显式传入时读取 `APP_HOST`、`APP_PORT` 环境变量或 `.env`，最后使用 `127.0.0.1:8000`。运行 PID 写入 `run/workbench.pid`，启动器输出写入 `logs/server.stdout.log` 和 `logs/server.stderr.log`。

打开 <http://127.0.0.1:8000>。接口文档位于 <http://127.0.0.1:8000/docs>。完整安装、部署和排障步骤见 [`docs/系统初始化与部署手册.md`](docs/系统初始化与部署手册.md)。

## 功能概览

### 对话与上下文

对话会自动保存到 SQLite。左侧会话列表支持新建、恢复、重命名和删除；刷新页面或重启服务后仍可继续对话。数据库默认位于 `data/workbench.db`，消息图片保存在 `data/assets/`，文档原文件保存在 `data/documents/`，三者均已被 Git 忽略。可使用 `DATABASE_PATH`、`ASSET_DIR` 和 `DOCUMENT_DIR` 修改位置。

每条历史消息提供按角色区分的操作：用户消息可以编辑，助手消息可以重试，双方消息都可以删除或从当前位置创建分支。编辑和重试默认创建独立分支并保留原会话；删除中间消息会明确提示并删除该消息及后续历史，同时清除失效的上下文摘要。分支复制会话设置和附件快照，删除父会话不会导致分支附件失效。生成期间可随时停止，已发送的用户消息会保留，不完整的助手回复不会写入消息历史。

发送后用户消息会立即显示，不需要等待模型开始回复。模型回复和多模型对比结果支持安全 Markdown、GFM 表格与任务列表、单换行、代码语法高亮与复制、LaTeX 数学公式、引用、链接和图片；模型返回的原始 HTML 不会执行。

长对话会在服务端按模型的 `context_window` 估算 Token。OpenAI Responses 模型使用 `tiktoken`，其他模型使用保守启发式估算；页面会明确展示估算方式。每个会话可选择自动裁剪、压缩摘要或超限阻止，摘要范围和版本会持久化；当前摘要使用本地抽取式压缩，不产生额外模型调用费用。

### 知识库与文档问答

“知识库”页面支持提前创建和维护可复用资料集合，可上传 TXT、Markdown、CSV、JSON、PDF 或 DOCX，也可把已有长期资料加入多个知识库。系统、知识库和单文档均可配置自动、递归、段落、Markdown、CSV 行或 Token 分块；单文档修改后由后台重新分块、递增版本并重建索引。聊天中可通过资料图标或 `/kb`、`/知识库`、`/file` 打开选择弹层，选择随会话持久化，输入框上方只保留紧凑来源标签。两类资料合并去重后使用直接上下文、词法、向量或混合检索。命中引用显示在助手回答下方，保存文档版本、作用域、知识库来源、分数、降级原因和片段快照；即使之后重新分块，旧回答仍能查看当时的片段。默认使用无需密钥的本地哈希向量，也可在“设置 > 知识库与 RAG”切换到 OpenAI-compatible Embedding 服务。向量服务或索引不可用时会自动降级到词法检索，不阻断问答。

### 多模型对比

“对比”模式可同时选择 2 至 6 个已配置的对话模型。各模型保存实际消息快照并通过独立分栏流式输出；单个模型失败或超时不会中断其他结果，终态也不会被迟到事件覆盖。对比历史、耗时、Token 和可选成本估算会持久化，结果可复制、重试或采纳到当前会话。默认全局并发为 4、同供应商并发为 2、单项超时为 120 秒。

### 调用参数、结构化输出与工具

对话、对比和生图页面的调用参数由模型目录动态决定。对话支持采样、输出上限、惩罚、随机种子、停止序列、推理等级和回答详略；对比只展示所选模型共同支持的参数；生图支持质量、格式、背景及有参考图时的保真度。空值不会发送给供应商，不支持的非空参数会在供应商调用前被后端拒绝。对比和生图历史保存有效参数快照，重试沿用原参数。

对话和对比支持可选的结构化输出与工具调用调试：可选择 JSON 对象或 JSON Schema，编辑工具定义 JSON，并设置工具选择策略。内置工具目录使用统一能力契约描述来源、执行方、风险、审批、权限、输入/输出 Schema、大小、超时、并行、幂等和数据去向；可把内置定义一键加入模型请求，也可编辑示例参数后直接试运行。当前内置 `current_time`、`calculator` 和代表性的 `text_inspector` 都是无网络、无文件副作用的本地纯函数。普通对话中，模型返回调用后仍由用户点击执行；自定义 Tool Schema 只能发送给模型，不能获得本地执行权限。“设置 > 工具与能力”可集中维护模型可见的自定义工具定义，这些定义只声明参数契约，不会在本机执行。

项目还提供默认关闭的实验性纯函数工具结果回传闭环。只有服务端设置 `EXPERIMENTAL_TOOL_LOOP_ENABLED=true` 且请求显式传入 `experimental_tool_loop=true` 时，已选中的内置纯函数工具才会自动执行并把结果回传模型；轮次、调用数和总时长均有上限。可使用 `.\.venv\Scripts\python.exe scripts\test_tool_result_loop.py --model-id <模型ID> --tool calculator --required` 进行真实供应商验证。该实验能力没有运行持久化、刷新恢复、审批、MCP、Skills 或多 Agent，不应作为完整 Agent 使用。

### 生图与图片编辑

生图模型声明 `image_edit` 能力后，页面会开放参考图上传。服务会解码验证图片、剥离 EXIF、记录尺寸并生成缩略图；提交生图时只传资产 ID。一次请求可生成多张输出并可选后台提交；多张输出、成功、失败或取消任务都会保存到可筛选分页的历史中；详情可查看参数、复制提示词、重试、删除单个版本或整条版本链后代，或沿版本时间线继续编辑。图片保留期限和磁盘上限可在“设置 > 图片存储”中管理。

参考图可分别标记为身份、外观、风格或构图用途，并可调整顺序。人物一致性辅助提供均衡、严格两档保护策略以及肖像、全身、生活场景模板；服务端会按参考图顺序生成确定性增强提示词，同时分别保存用户原始提示词和实际发送提示词。历史重试复用原任务的实际提示词快照，继续编辑默认把上一版本输出作为身份参考。该功能是基于多参考图和提示约束的生成辅助，不做人脸识别或身份认证，也不能消除供应商模型自身的一致性波动。

声明 `image_mask` 能力的 OpenAI Images 模型还会开放局部重绘和扩图。局部重绘提供画笔、擦除、笔刷大小、撤销、重做和清空工具，导出的 PNG 蒙版以透明区域表示需要修改的位置；扩图支持三种目标比例和九宫格原图位置，由服务端生成透明 PNG 画布及匹配蒙版。来源图、实际编辑底图和蒙版都会随任务持久化，详情可查看，重试直接复用已保存的派生资产。蒙版是模型的编辑引导，供应商不保证像素级严格贴边。

### 请求检查器、用量、模板与日志

主导航“请求”可查看聊天、对比、生图和图片编辑调用。检查器通过概览、请求、响应、时间线和代码标签展示脱敏内容、Token、排队/首 Token/总耗时及供应商请求 ID。Base64 和 API Key 不会进入检查器；记录级别、保留天数和最大记录数可在“设置”中调整。

主导航“用量”按 24 小时、7 天、30 天或自定义日期汇总调用次数、成功率、Token、平均/P95 耗时和估算成本，并支持按供应商、模型、调用类型和状态筛选。统计使用独立的轻量用量事件，不保存提示词、响应、图片、API Key 或 API Base；关闭或清理请求检查器不会删除用量。成本按调用开始时的模型目录单价快照估算，缺少价格或 Token 时显示未知，图片成本暂不估算，结果不等同于供应商账单。

主导航“模板”提供本地提示词模板库，可按名称、正文、分类和适用场景筛选，并支持新建、编辑、复制、删除以及 JSON 合并/替换导入和导出。模板变量使用 `{{variable_name}}` 格式；在对话、对比或生图输入区选择模板并填写变量后，只会替换当前提示词草稿，不会自动调用模型或改变模型、参数和附件。通用模板会出现在全部三个入口，专用模板只出现在对应场景。替换导入会二次确认，导入文件先完整校验再由 SQLite 事务原子写入。

主导航“日志”可查看、筛选、搜索和下载当前日志。服务日志以 JSON Lines 格式写入 `logs/app.log`，默认单文件 5 MB、保留 5 份轮转文件；API Key 会在写入前脱敏。

### 重试限流与配置安全

聊天、对比和生图调用共用供应商弹性层。默认单次尝试超时 120 秒，最多尝试 3 次；429、408、连接错误、超时和供应商 5xx 会按指数退避有限重试，认证、参数和模型错误立即失败。流式正文或工具调用一旦开始输出就不会自动重试。全局并发、单供应商并发、超时和退避参数可在“设置 > 重试与限流”中修改，保存后立即作用于当前进程，也可使用 `PROVIDER_*` 环境变量配置。

“设置 > 安全”提供敏感配置保护：API Key 和设置认证 Token 可使用 Fernet 加密写入 `.env`，密钥优先来自 `WORKBENCH_SECRET_KEY`，否则使用 `SECRET_KEY_PATH`（默认 `data/.secret.key`）。页面只显示密钥是否已配置，不会回显 Token。敏感设置和日志默认仅允许本机访问；如需远程管理，先设置 `ALLOW_REMOTE_SETTINGS=true` 并在安全页面配置至少 16 个字符的 Token，同时使用 HTTPS、网络访问控制和反向代理。安全访问会记录到 `AUDIT_LOG_PATH`（默认 `logs/audit.log`），记录中不包含密钥、Token 或请求正文。丢失外部密钥或本地密钥文件将无法解密既有密文，请纳入备份策略。

### 供应商连接与模型目录

“设置”将供应商连接和模型目录分开管理。供应商连接保存在 `config/providers.yaml`，可以从 OpenAI、Anthropic、DeepSeek、Qwen、OpenRouter、xAI、Groq、Mistral、Moonshot、SiliconFlow、智谱或 Gemini 模板创建，也可以完全自定义。模板会预填名称、环境变量、API Base URL、模型列表协议和路径，保存前均可修改。供应商支持编辑、停用和删除；仍有关联模型时禁止删除，停用后关联模型不可调用。

供应商连接页可以保存或更新各平台密钥和 API Base URL，通过 3 次轻量模型列表请求检查连接、认证和响应速度，并按需从 OpenAI-compatible 或 Anthropic 接口探查当前账号可见模型；模型目录页支持新增、编辑、启停和删除本地模型，并集中管理调用协议、能力、上下文、默认参数和价格。模型的能力决定它出现在对话、对比还是生图功能中；模型停用、供应商停用或缺少 Key 时，业务页面会同步显示具体原因并禁止调用。页面重新获得焦点时会主动刷新目录，其他窗口或手工配置产生的变化无需整页重载即可同步。测速不会调用生成接口，结果展示首次、平均、最快和最慢响应。应用只返回密钥是否已配置，不会把已有密钥回传浏览器。配置默认只允许本机访问，密钥和 URL 覆盖值写入被 Git 忽略的 `.env` 并立即生效。

探查结果不会自动覆盖本地目录。选择远端模型后，需要确认本地 ID、实际调用模型名、transport、能力、上下文、默认参数和可选价格，再批量导入 `config/models.yaml`。手工新增、编辑、启停、删除和批量导入均执行完整目录校验、原子写入，并在变更前自动备份到 `data/config-backups/`。模型 ID 和所属供应商创建后不可修改，避免破坏会话与任务历史中的引用；删除模型不会删除既有历史记录。供应商列表通常只代表账号可见性，不保证模型一定可调用；能力建议根据模型名称和现有连接生成，需按供应商文档核对。

HTTPS 和本机 HTTP 地址可以直接保存。非本机 HTTP 地址需要在界面中显式确认明文传输风险后保存，以兼容只提供 HTTP 的内网或第三方服务。

若确实需要从其他机器管理配置，可设置 `ALLOW_REMOTE_SETTINGS=true`，但应先在 FastAPI 前增加身份认证和 HTTPS；不建议直接暴露到公网。

## 配置模型

供应商注册表在 `config/providers.yaml`，定义稳定 ID、显示名称、类别、启用状态、密钥与 URL 环境变量、默认 API Base URL 及模型探查协议。模型目录在 `config/models.yaml`；模型通过 `provider_id` 引用供应商，加载时以供应商注册表中的连接配置为准。旧模型条目内的连接字段仍兼容。

每个模型可以配置：

- `model`：实际发送给 SDK 的模型名；LiteLLM 模型通常带厂商前缀。
- `transport`：`openai_responses`、`openai_images`、`litellm_chat` 或 `litellm_image`。
- `provider_id`：关联 `config/providers.yaml` 中的供应商稳定 ID。
- `capabilities`：`chat`、`vision`、`reasoning`、`image_generation`、`image_edit`、`image_mask`。其中 `image_edit` 表示模型支持参考图输入；`image_mask` 表示已验证可通过 OpenAI Images 蒙版参数执行局部重绘和扩图，并且必须同时配置 `image_edit`。
- `supported_parameters`：模型实际开放的高级调用参数；缺省时按协议和能力兼容推导，显式空列表表示不开放高级参数。
- `defaults`：各支持参数的可选默认值；空值表示沿用供应商默认行为。
- `context_window`：模型上下文窗口，用于发送前的 Token 预算和历史裁剪。
- `input_cost_per_million` / `output_cost_per_million`：可选 USD 单价，用于对比结果和用量报表的成本估算。

例如先在 `config/providers.yaml` 定义连接，再在 `config/models.yaml` 添加一个支持参考图编辑的模型：

```yaml
# config/providers.yaml
providers:
  - id: company
    name: Company Gateway
    category: custom
    enabled: true
    api_key_env: COMPANY_API_KEY
    api_base_env: COMPANY_API_BASE
    api_base: http://127.0.0.1:9000/v1
    discovery:
      transport: openai_compatible
      path: models

# config/models.yaml
models:
  - id: company-image
    name: Company Image
    provider_id: company
    model: gpt-image-compatible
    transport: openai_images
    capabilities: [image_generation, image_edit, image_mask]
```

`api_key_env` 与 `api_base_env` 必须指向不同用途的环境变量；把密钥变量误填到 `api_base_env` 会让密钥值被当作 API Base URL 回传给浏览器。供应商会调整模型名称、区域地址和账户权限；示例目录是起点，实际使用时以账户控制台为准。OpenAI 的 API 计费与 ChatGPT 订阅相互独立。

## 数据备份

执行 `scripts/workbench.* stop` 停止写入后，一并备份 `data/workbench.db`、`data/assets/`、`data/documents/`、`config/providers.yaml`、`config/models.yaml`、`.env` 和 `data/.secret.key`。数据库包含会话、摘要、对比、生图关系、文档分块、知识库、工具定义、请求检查器记录和独立用量事件，图片和文档正文分别在资产目录与文档目录中；只备份其中一项会造成记录、图片、文档或连接配置缺失。`.env` 含凭据，应使用受控权限和加密备份。恢复时保持相同目录结构，再启动服务。

“设置 > 导入与导出”提供应用内归档：可导出单个会话包、生图任务版本链包或完整工作区备份，导入前先上传预览并校验清单、哈希与容量，再选择合并或替换写入；替换需要二次确认并会先自动备份当前工作区。归档不包含 `.env`、密钥文件和日志，恢复后仍需重新配置缺失的密钥。

## 前端开发

默认入口已经切换为 React 工作台，技术栈为 React、TypeScript、Vite、React Router、TanStack Query 和基于 Radix 的 shadcn/ui 本地组件。旧版页面保留在 <http://127.0.0.1:8000/legacy>，用于迁移期回退。

开发时可以使用开发脚本同时启动带热重载的 FastAPI 和 Vite：

```powershell
.\scripts\workbench-dev.ps1 start
```

Windows 命令提示符：

```bat
scripts\workbench-dev.bat start
```

Linux / macOS：

```sh
chmod +x scripts/workbench-dev.sh
./scripts/workbench-dev.sh start
```

开发页面位于 <http://127.0.0.1:5173>，后端 API 位于 <http://127.0.0.1:8000>。Vite 会代理 `/api` 请求，修改 React/TypeScript/CSS 后自动热更新，修改 Python 后由 Uvicorn 自动重载。开发脚本同样支持 `start`、`stop`、`restart` 和 `status`，使用独立的 PID 文件和 `logs/dev-*.log`，不会把前端重新打包进后端。

生产脚本和开发脚本默认都会使用后端端口 `8000`，不能同时启动。切换到开发模式前可先执行 `workbench.* stop`，或者为开发脚本指定其他后端端口。

PowerShell 可通过 `-BindHost`、`-Port`、`-FrontendHost`、`-FrontendPort` 覆盖地址；Shell 对应位置参数为 `[backend-host] [backend-port] [frontend-host] [frontend-port]`。也可设置 `APP_HOST`、`APP_PORT`、`FRONTEND_HOST` 和 `FRONTEND_PORT`。脚本会把实际后端地址传给 Vite 代理。

也可以分别在两个终端手动启动：

```powershell
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

```powershell
cd frontend
npm ci
npm run dev
```

现有 `workbench.ps1/.bat/.sh` 仍是生产式启动脚本：它们只启动 FastAPI，并直接提供已经构建到 `app/static/ui/` 的页面。发布或需要从 `8000` 使用最新前端时先执行生产构建：

```powershell
cd frontend
npm run api:generate  # 仅在 FastAPI OpenAPI 契约变更后执行
npm run build
```

`/chat`、`/compare`、`/images`、`/knowledge-bases`、`/templates`、`/requests`、`/usage`、`/logs` 和 `/settings/*` 均支持浏览器直接访问与刷新；未知 `/api/*` 仍返回 JSON 404，不会落入 SPA 页面。

## 验证

```powershell
pytest
ruff check .
cd frontend
npm run typecheck
npm run lint
npm test
npx playwright install chromium webkit
npm run test:e2e
```

生产环境可使用 `requirements.txt` 只安装后端运行依赖，开发环境使用 `requirements-dev.txt`；前端依赖使用 `cd frontend; npm ci`。

## 文档

- [技术文档索引](docs/技术文档索引.md)：全部资料入口，含手册、功能专项文档目录、文档约定和阅读顺序。
- [项目现状分析](docs/项目现状分析.md)：规模、功能完成度、质量门禁实测、已知问题和下一步建议。
- [需求说明](docs/REQUIREMENTS.md)、[总体架构](docs/ARCHITECTURE.md)、[待办事项](docs/TODO.md)：产品边界、设计决策和 26 项功能路线图。
- [系统初始化与部署手册](docs/系统初始化与部署手册.md)、[后端开发技术文档](docs/后端开发技术文档.md)、[前端开发技术文档](docs/前端开发技术文档.md)、[完整用户手册](docs/完整用户手册.md)。
- `docs/features/`：各功能的需求分析、方案设计、详细实施计划和测试报告，以及智能体、工具与 MCP 的演进规划和决策记录。
- [DeepSeek Harness 复用与迁移评估](docs/DEEPSEEK_HARNESS_EVALUATION.md)。

OpenAI 实现参考官方文档：[图片生成与编辑](https://developers.openai.com/api/docs/guides/image-generation)、[图片与视觉](https://developers.openai.com/api/docs/guides/images-vision/) 和 [流式响应](https://developers.openai.com/api/docs/guides/streaming-responses/)。