ernie-image-gen

Files (15)

• SKILL.md
• openai.yaml · agents/
• cloud-config.portable.cn.yaml · assets/
• cloud-config.portable.yaml · assets/
• ernie-image-gen.example.yaml · assets/
• local-config.portable.cn.yaml · assets/
• local-deploy.md · references/
• portable-usage.md · references/
• prompting.md · references/
• service-config-and-api.md · references/
• __init__.py · scripts/
• common.py · scripts/
• generate_image.py · scripts/
• health_check.py · scripts/
• validate_config.py · scripts/

SKILL.md (first lines)

# ERNIE Image Gen

使用 ERNIE Image 做文生图，默认走**服务调用模式**，并支持切换到兼容原生 `/generate` 接口的模式。这个 skill 适合：

- 需要通过配置切换不同 ERNIE Image 服务地址
- 需要保留 `model_dir` / `weight_tar_path` 等部署上下文，但不希望写死本机路径
- 需要中文优先、多语言混合、长文本、多区域文本渲染
- 需要把生成图片和元数据稳定落盘到当前项目或当前任务目录

## 默认逻辑：云端优先，本地显式触发

这个 skill 的默认行为是：

1. **优先采用云端模型服务**
   - 默认优先找云端配置
   - 默认优先使用 `assets/cloud-config.portable.cn.yaml`
   - 默认优先走 `openai_compatible`
2. **如果云端配置还没完成**
   - 不要直接假设本地模型
   - 先引导使用者补齐最少配置：`base_url`、`auth_token_env`、`mode`
   - 配完后先做 `health_check.py`，再生成
3. **只有在用户明确说明要用本地模型时**
   - 才切到本地配置路径
   - 才使用本地权重 / 本地部署上下文
   - 才优先参考 `assets/local-config.portable.cn.yaml`

## 使用者先配置这几项

无论是在另一台电脑、另一个项目，还是分享给别人用，优先检查这 5 项：

1. `base_url`
   - 改成你自己的 ERNIE Image 服务地址
2. `auth_token_env`
   - 填“环境变量名”，不是 API Key 本身
   - 例如：`ERNIE_IMAGE_API_KEY`
3. `mode`
   - OpenAI 兼容接口用 `openai_compatible`
   - 原生接口用 `native_generate`
4. `output.artifact_dir`
   - 推荐保留 `${ERNIE_IMAGE_ARTIFACT_DIR:-./achievement}`
   - 不写死本机绝对路径
5. `weight_tar_path`
   - 如果只是调远程服务，可以留空
   - 只有在你要保留本地部署上下文时才需要填

推荐直接从这两个模板开始：

- 通用英文模板：`assets/cloud-config.portable.yaml`
- 通用中文模板：`assets/cloud-config.portable.cn.yaml`
- 本地模型中文模板：`assets/local-config.portable.cn.yaml`

如果你只是普通云端调用，最常用的动作其实只有两步：

```bash
export ERNIE_IMAGE_API_KEY='你的key'
python3 scripts/generate_image.py --config assets/cloud-config.portable.cn.yaml --prompt '一只可爱的橘猫表情包'
```

## Quick Start

### A. 默认：云端服务调用

1. 优先复制可移植云端模板，而不是项目私有模板：
   - `assets/cloud-config.portable.cn.yaml`
   - 或 `assets/cloud-config.portable.yaml`
2. 按需修改：
   - `mode`: `openai_compatible` 或 `native_generate`
   - `base_url`
   - `auth_token_env`
   - `model_dir`（通常不用改）
   - `weight_tar_path`（可留空，或用环境变量占位）
   - 输出目录 `output.artifact_dir`（推荐相对路径或环境变量）
3. 先做健康检查：

```bash
python3 scripts/health_check.py \
  --config assets/cloud-config.portable.cn.yaml
```

4. 生成图片：

```bash
python3 scripts/generate_image.py \
  --config assets/cloud-config.portable.cn.yaml \
  --prompt "一只戴宇航员头盔的橘猫，电影感打光，超高细节"
```

### B. 仅当用户明确要求：本地模型调用

1. 复制本地模板：
   - `assets/local-config.portable.cn.yaml`
2. 重点修改：
   - `base_url`
   - `mode`
   - `model_dir`
   - `weight_tar_path`
   - `output.artifact_dir`
3. 再执行：

```bash
python3 scripts/health_check.py \
  --config assets/local-config.portable.cn.yaml
```

```bash
python3 scripts/generate_image.py \
  --config assets/local-config.portable.cn.yaml \
  --prompt "一只戴宇航员头盔的橘猫，电影感打光，超高细节"
```

更详细的跨机器/跨项目使用方式见：

- `references/portable-usage.md`

## Mode Decision

### 默认：`openai_compatible`

优先调用：

From AgenticAIPlan/AgenticAISkills, MIT.

More from AgenticAIPlan/AgenticAISkills