chongming-plugins/doubao/README.md

# Doubao Worker 插件

火山引擎豆包（Doubao）视觉理解模型集成，支持图像分析与描述生成。

---

## 功能

- 接收 **base64 编码**的图片和**提示词**（prompt）
- 调用火山引擎豆包视觉模型 API
- 支持**思考模式**（thinking mode），模型会先推理再输出结果
- 返回模型生成的图像描述文本

---

## 配置

在 `config/workers/doubao/config.toml` 和 `config/workers/config.toml` 中设置：

```toml
[workers.config]
type = "doubao"
api_key = "<your-api-key>"                                  # 火山引擎 API Key（也可通过环境变量 VOLC_ACCESSKEY 提供）
base_url = "https://ark.cn-beijing.volces.com/api/v3"       # API 端点
model = "doubao-seed-evolving"                              # 模型名称
```

---

## API 端点

### `POST /doubao/analyze` — 图像分析

```json
// 请求
{
  "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "prompt": "描述这张图片的内容"
}

// 响应
{
  "result": "图片中是一只橘猫坐在米色沙发上，阳光从窗户照进来...",
  "error": ""
}
```

| 参数           | 类型  | 必填 | 说明                                                        |
| -------------- | ----- | ---- | ----------------------------------------------------------- |
| `image_base64` | `str` | ✅   | Base64 编码的图片数据（可含 `data:image/...;base64,` 前缀） |
| `prompt`       | `str` | ✅   | 给模型的提示词，描述期望的分析内容                          |

---

## 支持的模型

| 模型                   | 说明                         |
| ---------------------- | ---------------------------- |
| `doubao-seed-evolving` | 豆包视觉理解旗舰模型（默认） |

可根据火山引擎最新文档更换 `model` 配置项。

---

## 实现细节

- 使用 `httpx` 异步 HTTP 客户端调用火山引擎 API
- 支持流式响应（streaming）中的思考模式 token
- API Key 优先从环境变量 `VOLC_ACCESSKEY` 读取
- 超时时间默认 30 秒，在 `config.toml` 的 `defaults.timeout` 中配置

---

## 依赖

| 工具包             | 用途                                 |
| ------------------ | ------------------------------------ |
| `httpx`            | 异步 HTTP 客户端                     |
| `chongming-worker` | `@rpc_method` 装饰器 + Worker 运行时 |