# toolkit

**Repository Path**: dylanan/toolkit

## Basic Information

- **Project Name**: toolkit
- **Description**: 一个集多种工具于一体的开源项目，旨在为开发者提供高效、便捷的开发支持，涵盖代码生成、调试、测试等功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 工具箱

一个支持本地运行和服务器部署的 AI 工具箱，目前包含两类能力：

- 域名查询：支持单个域名查询，也支持上传带有 `domain` 列的 CSV 做批量查询
- 文本翻译：支持单条文本翻译，也支持上传 CSV 后按指定列批量翻译

域名查询导出为新的 UTF-8 CSV：

- `domain`
- `company_name`
- `industry`
- `ai_details`

其中 `ai_details` 始终是 JSON 字符串，结构固定如下：

```json
{
  "企业概况": "对该单位/网站的简要介绍",
  "引用的链接": ["https://example.com"]
}
```

无信息时输出 `{}`；无链接时输出 `"引用的链接": []`。

## 已实现能力

- 批量读取 CSV 中的 `domain` 列
- 支持单个域名即时查询
- 支持单条文本翻译
- 支持 CSV 指定列批量翻译，并将译文追加到新列
- 同批次自动去重，避免重复查询
- 本地 SQLite 缓存，重复运行时可直接复用历史结果
- 行业分类会优先归入系统预置行业；没有合适项时才新增，并尽量避免“互联网/信息技术”这类语义重复名称
- 页面内可直接维护“已知行业库”；任务会基于这份行业库判断是否新增行业，并把新增结果自动回写形成闭环
- 支持切换 `Azure OpenAI` 和 `Gemini`
- 翻译支持切换 `Azure OpenAI` 和 `GPUStack` 本地大模型
- 输出 CSV 编码为 `UTF-8 with BOM`，兼容 Windows Excel
- 无法识别的域名自动留空或输出 `{}`
- 支持浏览器本地界面，也支持命令行执行
- 支持 Docker / Docker Compose 部署
- 支持后台任务队列，页面关闭后任务继续运行

## 目录说明

- `/Users/dylan/Documents/dylan/工具/cli.py`
  命令行入口
- `/Users/dylan/Documents/dylan/工具/server_app.py`
  服务器部署入口
- `/Users/dylan/Documents/dylan/工具/worker.py`
  后台任务 Worker
- `/Users/dylan/Documents/dylan/工具/docker-compose.yaml`
  服务器部署编排文件
- `/Users/dylan/Documents/dylan/工具/Dockerfile`
  容器构建文件
- `/Users/dylan/Documents/dylan/工具/domain_lookup_tool`
  核心处理逻辑
- `/Users/dylan/Documents/dylan/工具/outputs`
  导出结果目录
- `/Users/dylan/Documents/dylan/工具/cache`
  本地缓存目录

## 安装依赖

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
```

## 本地启动

本地默认入口已经切换到新的 Web 系统，也就是 `FastAPI + worker` 这一套，界面地址为 [http://localhost:8051](http://localhost:8051)。

启动前请先准备一个可用的 Redis：

```bash
redis-server
```

如果 Redis 不在本机 `127.0.0.1:6379`，可以先设置：

```bash
export REDIS_URL=redis://your-host:6379/0
```

本地启动脚本会优先读取项目根目录下的 `deploy.env`，因此如果你已经在里面配置了 `REDIS_HOST`、`REDIS_PORT`、`REDIS_DB` 或 `REDIS_URL`，通常不需要再手动导出环境变量。

macOS:

```bash
chmod +x run_local_tool.command
./run_local_tool.command
```

Windows:

```bat
run_local_tool.bat
```

上面两个脚本会默认做三件事：

- 把 `REDIS_URL` 设为 `redis://127.0.0.1:6379/0`（如果你没手动指定）
- 启动 `worker.py`
- 启动 `server_app.py` 对应的 Web 服务

也可以手动分开启动：

```bash
python3 worker.py
```

```bash
python3 -m uvicorn server_app:app --host 0.0.0.0 --port 8051
```

启动后浏览器访问 [http://localhost:8051](http://localhost:8051)。

页面包含两个入口：

- `域名查询`：支持单个查询和批量查询
- `文本翻译`：支持单条翻译和 CSV 批量翻译

## Docker 部署

适合直接部署到 Linux 服务器。当前容器化结构如下：

- `web`
  FastAPI Web 服务，负责页面、上传、任务创建、状态查询和结果下载
- `worker`
  RQ Worker，负责实际查询任务

这样做的好处是：

- 任务提交后进入后台队列
- 浏览器关闭、页面刷新、用户断开连接后，任务仍会继续执行
- 结果文件和任务数据会保存在 Docker volume 中

### 启动

先准备部署配置文件：

```bash
cp deploy.env.example deploy.env
vim deploy.env
```

例如填写你的远程 Redis：

```env
REDIS_HOST=10.0.0.25
REDIS_PORT=6379
REDIS_DB=0
# REDIS_PASSWORD=your_password
```

先构建镜像：

```bash
docker build -t domain-lookup-tool:latest .
```

然后启动：

```bash
docker compose up -d
```

如果你希望把配置文件放在项目目录外，例如：

```text
/opt/domain-lookup/deploy.env
```

可以这样启动：

```bash
DEPLOY_ENV_FILE=/opt/domain-lookup/deploy.env docker compose up -d
```

如果 Redis 就跑在同一台服务器宿主机上，推荐配置为：

```env
REDIS_HOST=host.docker.internal
REDIS_PORT=6379
REDIS_DB=0
```

这里不要写 `127.0.0.1`，因为容器里的 `127.0.0.1` 指向容器自己，不是宿主机。

启动后访问：

```text
http://你的服务器IP:8051
```

### 停止

```bash
docker compose down
```

如果要连同 Redis 和任务数据一起清理：

```bash
docker compose down -v
```

### 数据保存位置

容器内统一保存到：

```text
/app/data
```

其中包含：

- `jobs/`
  每个任务的输入文件、结果 CSV、预览 JSON
- `cache/`
  域名查询缓存

### 后台任务说明

- 提交单个域名或 CSV 后，服务会立即返回任务页面
- 任务状态页面会自动轮询更新
- 即使关闭当前页面，`worker` 仍会继续处理
- 处理完成后，可重新打开任务详情页下载结果 CSV

### Redis 配置文件

- 默认读取项目根目录下的 `deploy.env`
- `deploy.env` 通过 `docker-compose.yaml` 的 `env_file` 注入容器环境变量
- `env_file` 不会作为容器内挂载文件使用，它只是把变量传给容器
- 现在 `deploy.env` 已经被排除在 Docker 镜像构建上下文之外，不会被打包进镜像
- 你可以在里面配置：
- `REDIS_HOST`
- `REDIS_PORT`
- `REDIS_DB`
- `REDIS_PASSWORD`
- 如果你已经有完整连接串，也可以直接配置：
- `REDIS_URL=redis://host:port/db`
- 如果你想把配置文件挂在项目外部，推荐通过环境变量指定：
- `DEPLOY_ENV_FILE=/opt/domain-lookup/deploy.env`

## 配置说明

### Azure OpenAI

域名查询或文本翻译使用 Azure OpenAI 时，界面中需要填写：

- `Azure URL`
- `Azure deployment`
- `Azure Key`
- `模型名（可选）`

说明：

- 当前实现会优先用 `deployment` 发起请求，满足 Azure 资源的实际调用要求
- 已有 deployment 时，不强制要求填写模型名
- 如果模型支持，可勾选 `Azure Web Search`
- URL 支持填写资源根地址，例如 `https://your-resource.openai.azure.com`

### Gemini

界面中需要填写：

- `模型名`
- `Gemini Key`

说明：

- 可选启用 `Google Search grounding`，便于返回引用链接

### GPUStack

文本翻译使用 GPUStack 时，界面中需要填写：

- `GPUStack 地址`
- `模型名`
- `GPUStack API Key（可选）`

说明：

- 当前按 OpenAI 兼容接口调用，默认会拼接到 `/v1/chat/completions`
- 如果你已经填写了带 `/v1` 或 `/v1-openai` 的地址，也可直接使用
- 适合接入本地部署的大模型做内部翻译任务

## 命令行用法

Azure:

```bash
python3 cli.py \
  --domain example.com \
  --output outputs/single_result.csv \
  --provider azure \
  --model-name gpt-4.1 \
  --azure-endpoint https://your-resource.openai.azure.com \
  --azure-deployment your-deployment \
  --azure-api-key your-key
```

Azure 批量:

```bash
python3 cli.py \
  --input domain_batch_import_template.csv \
  --output outputs/result.csv \
  --provider azure \
  --model-name gpt-4.1 \
  --azure-endpoint https://your-resource.openai.azure.com \
  --azure-deployment your-deployment \
  --azure-api-key your-key
```

Gemini 单个:

```bash
python3 cli.py \
  --domain example.com \
  --output outputs/single_result.csv \
  --provider gemini \
  --model-name gemini-2.5-pro \
  --gemini-api-key your-key
```

Gemini 批量:

```bash
python3 cli.py \
  --input domain_batch_import_template.csv \
  --output outputs/result.csv \
  --provider gemini \
  --model-name gemini-2.5-pro \
  --gemini-api-key your-key
```

## 输入格式

输入 CSV 至少需要 `domain` 列，例如：

```csv
domain,company_name,industry,ai_details
example.com,示例公司,制造业,"{""企业概况"":""示例说明"",""引用的链接"":[""https://example.com""]}"
mail.example.com,示例公司,制造业,"{""企业概况"":""""，""引用的链接"":[]}"
unknown.com,,,{}
```

工具实际处理时只读取 `domain` 列，其他列会忽略，并重新生成固定格式结果。

## 跨平台说明

- Windows：可直接运行 `run_local_tool.bat`
- macOS：可直接运行 `run_local_tool.command`
- iOS / iPadOS：当前实现为本地网页工具，适合通过 Safari 访问一台已经启动服务的设备；不直接在 iPhone 本机运行 Python
- Linux 服务器：推荐使用 Docker Compose 部署 `web + worker + redis`

如果后续需要，我也可以继续把它打包成 Windows 可执行文件，或者再补一个更正式的桌面版壳子。