vtxf-free-siliconflow✓ Pass

SKILL.md Content

---
slug: vtxf-free-siliconflow
version: 0.2.0
displayName: 硅基流动免费小模型调用
name: vtxf-free-siliconflow
description: Use when 需要调用硅基流动（SiliconFlow）免费小模型——覆盖文本对话/推理、翻译、图片OCR、文本向量化、文档重排序、文生图、语音转文字（ASR）七大能力
tags: [siliconflow, free, llm, ocr, embed, rerank, image, asr]
summary: 零依赖 Node.js CLI（scripts/sf.mjs），统一封装 16 个免费小模型
---

# vtxf-free-siliconflow

硅基流动（SiliconFlow）免费模型统一调用工具：一个零依赖 Node.js CLI，封装 16 个免费小模型，覆盖对话、翻译、OCR、嵌入、重排、生图、语音七大能力。⚠️ 这些是免费小模型，能力相对较弱，适合简单任务；复杂或高质量需求请用付费大模型。

---

## 概述

提供单文件 CLI（`scripts/sf.mjs`），以 subcommand 方式调用硅基流动 API（OpenAI 兼容）。纯薄封装，面向 AI 消费：结构化 JSON 输出、模型短名自动解析、零 npm 依赖。

**适用场景**：
- **简单对话/简单推理**：用 GLM-4-9B-0414（快）或 DeepSeek-R1（简单推理）做问答、简单解题、文本生成
- **文本翻译**：用 translate 子命令（默认 Hunyuan-MT-7B 翻译专用）做中英互译等
- **OCR**：用 DeepSeek-OCR 识别图片文字、还原表格为 Markdown
- **嵌入**：用 bge-m3 / bge-large-zh 做文本向量化，支撑语义检索
- **重排**：用 bge-reranker-v2-m3 对召回文档精排，RAG 必备
- **生图**：用 Kolors 按中文提示词生成图片
- **语音转写**：用 SenseVoiceSmall 把音频转为文字（附情绪识别）

---

## 前置依赖

- **Node.js ≥ 18**（使用原生 `fetch`/`FormData`/`Blob`/`AbortController`，零 npm 依赖）
- **环境变量 `SILICONFLOW_API_KEY`**：硅基流动 API Key

### API Key 获取

在 [硅基流动官网](https://cloud.siliconflow.cn/i/4xYXeAIS) 注册后，于「API 密钥」页面创建。

#### 多平台命令行（永久生效）

```bash
# Windows PowerShell
[Environment]::SetEnvironmentVariable("SILICONFLOW_API_KEY", "sk-xxxxx", "User")

# Windows CMD
setx SILICONFLOW_API_KEY "sk-xxxxx"

# Linux/macOS (bash)
echo 'export SILICONFLOW_API_KEY="sk-xxxxx"' >> ~/.bashrc && source ~/.bashrc

# Linux/macOS (zsh)
echo 'export SILICONFLOW_API_KEY="sk-xxxxx"' >> ~/.zshrc && source ~/.zshrc
```

> Windows 修改环境变量后，需关闭全部 VSCode/终端实例再重开才能读到新值。

#### Windows 手动操作（GUI）

1. 按 `Win + R`，输入 `sysdm.cpl` 回车（或右键「此电脑」→「属性」→「高级系统设置」）
2. 「高级」选项卡 →「环境变量」按钮
3. 「用户变量」区点「新建」：变量名填 `SILICONFLOW_API_KEY`，变量值填 Key
4. 点「确定」×3 关闭所有窗口
5. 关闭并重开 VSCode/终端使配置生效

> 定位脚本目录：技能位于 本仓库 `skills/vtxf-free-siliconflow/`，下文用 `<SKILL_DIR>` 表示。

---

## CLI 用法

```bash
node <SKILL_DIR>/scripts/sf.mjs <子命令> [选项]
```

### 通用约定

- **输出**：stdout 始终为结构化 JSON；成功 `{ok:true, ...}`，失败 `{ok:false, error, ...}` 且退出码 1
- **进度静默**：所有中间过程不输出，仅最终结果 JSON
- **`--model`**：传短名（如 `GLM-4-9B-0414`）自动解析为完整 ID（`THUDM/GLM-4-9B-0414`）；含 `/` 视为完整 ID；大小写不敏感
- **文件输入**：`--input`/`--docs` 的值若为已存在文件路径则读取每行一条，支持 `@文件` 语法与 `a|||b|||c` 分隔
- **超时**：默认 120s（生图 180s、OCR 90s）

### 1. models — 列出可用模型

```bash
node <SKILL_DIR>/scripts/sf.mjs models [--type chat|ocr|embed|rerank|image|asr]
```

```bash
# 列全部 16 个模型
node <SKILL_DIR>/scripts/sf.mjs models
# 只看对话模型
node <SKILL_DIR>/scripts/sf.mjs models --type chat
```

### 2. chat — 文本对话/推理

```bash
node <SKILL_DIR>/scripts/sf.mjs chat --model <别名> --prompt "<提问>" [--system "<系统提示>"] [--history <msg.json>] [--stream] [--max-tokens N] [--temperature F]
```

```bash
# 快速问答（GLM-4-9B 性价比之王）
node <SKILL_DIR>/scripts/sf.mjs chat --model GLM-4-9B-0414 --prompt "用一句话解释什么是 RAG"

# 推理模型解题（含思考链 reasoning 字段）
node <SKILL_DIR>/scripts/sf.mjs chat --model DeepSeek-R1-0528-Qwen3-8B --prompt "证明根号2是无理数"

# 带系统角色设定
node <SKILL_DIR>/scripts/sf.mjs chat --model GLM-4-9B-0414 --system "你是资深 Python 工程师" --prompt "解释装饰器"

# 多轮对话（--history 传 messages 数组 JSON）
node <SKILL_DIR>/scripts/sf.mjs chat --model GLM-4-9B-0414 --history ctx.json --prompt "接着上文继续"
```

> **关于 max_tokens**：默认**不传**该参数，让模型按自身上限输出（避免推理模型思考链被截断，实测 Qwen3.5-4B 默认即完整输出）。仅当需限制长度时用 `--max-tokens`。

> **翻译请用 `translate` 子命令**（Hunyuan-MT-7B 翻译专用，见下节），勿用 chat 通用对话替代。

### 3. translate — 文本翻译

```bash
node <SKILL_DIR>/scripts/sf.mjs translate --text "<待翻译文本>" [--text ...] [--source <语言码>] [--target <语言码>] [--model <别名>] [--max-tokens N]
```

```bash
# 翻译成中文（默认 source=auto, target=zh）
node <SKILL_DIR>/scripts/sf.mjs translate --text "Hello, how are you?"

# 翻译成英文
node <SKILL_DIR>/scripts/sf.mjs translate --text "今天天气真好，我们一起去公园吧。" --target en

# 指定源语言（source 默认 auto 自动检测）
node <SKILL_DIR>/scripts/sf.mjs translate --text "Bonjour tout le monde" --source fr --target zh

# 从文件批量翻译（每行一条）
node <SKILL_DIR>/scripts/sf.mjs translate --text @lines.txt --target en
```

> **语言码**：`zh`(中文) / `en`(英文) / `ja`(日文) / `ko`(韩文) / `fr`(法文) / `de`(德文) / `ru`(俄文) / `es`(西班牙文) / `pt` / `it` / `ar` / `th` / `vi`，`source` 可用 `auto` 自动检测。
>
> **模型**：默认 `Hunyuan-MT-7B`（翻译专用），一般无需换；`--model` 可覆盖。自动注入"只输出译文"系统指令，结果在 `results[].translated`。
>
> **提示**：默认 target=zh（面向中文用户）；英译中/中译英最常用，需其它目标语言时显式传 `--target`。

### 4. ocr — 图片文字识别

```bash
node <SKILL_DIR>/scripts/sf.mjs ocr --model <别名> --image <路径|URL> [--image ...] [--prompt "<指令>"]
```

```bash
# 识别本地图片（DeepSeek-OCR，自动还原表格为 Markdown）
node <SKILL_DIR>/scripts/sf.mjs ocr --model DeepSeek-OCR --image receipt.png

# 多图一起识别
node <SKILL_DIR>/scripts/sf.mjs ocr --model DeepSeek-OCR --image page1.png --image page2.png

# 识别网络图片
node <SKILL_DIR>/scripts/sf.mjs ocr --model DeepSeek-OCR --image https://example.com/doc.png

# 自定义识别指令
node <SKILL_DIR>/scripts/sf.mjs ocr --model DeepSeek-OCR --image table.png --prompt "提取表格为 Markdown，只输出表格"
```

### 5. embed — 文本向量化

```bash
node <SKILL_DIR>/scripts/sf.mjs embed --model <别名> --input <文本|@文件> [--input ...] [--save-vecs <文件>]
```

```bash
# 单条文本
node <SKILL_DIR>/scripts/sf.mjs embed --model bge-m3 --input "苹果公司总部在加州"

# 多条文本（对比/批量）
node <SKILL_DIR>/scripts/sf.mjs embed --model bge-large-zh-v1.5 --input "今天天气不错" --input "明日有雨"

# 从文件读（每行一条）
node <SKILL_DIR>/scripts/sf.mjs embed --model bge-m3 --input @docs.txt

# 指定向量保存路径（默认存系统临时文件，stdout 给 vecFile 路径）
node <SKILL_DIR>/scripts/sf.mjs embed --model bge-m3 --input "测试" --save-vecs vec.json
```

> **向量输出策略**：向量本体写入文件（默认临时文件，可 `--save-vecs` 指定），stdout 只给 `{dim, count, usage, vecFile}`，避免 1024 维数组撑爆输出。

### 6. rerank — 文档重排序

```bash
node <SKILL_DIR>/scripts/sf.mjs rerank --model <别名> --query "<查询>" --docs <文本|@文件|a|||b> [--docs ...] [--top-n N]
```

```bash
# 查询重排（||| 分隔多条文档）
node <SKILL_DIR>/scripts/sf.mjs rerank --model bge-reranker-v2-m3 --query "苹果公司总部在哪" --docs "苹果总部在库比蒂诺|||苹果是一种水果|||微软总部在雷德蒙德"

# 从文件读文档（每行一条）
node <SKILL_DIR>/scripts/sf.mjs rerank --model bge-reranker-v2-m3 --query "什么是 RAG" --docs @docs.txt --top-n 3
```

### 7. image — 文生图

```bash
node <SKILL_DIR>/scripts/sf.mjs image --model <别名> --prompt "<提示词>" [--size 1024x1024] [--steps 30] [--out <文件.png>]
```

```bash
# 中文提示词生图（Kolors）
node <SKILL_DIR>/scripts/sf.mjs image --model Kolors --prompt "一只橘猫坐在窗台，窗外江南水乡，水墨国风" --out cat.png

# 指定尺寸（默认 1024x1024）
node <SKILL_DIR>/scripts/sf.mjs image --model Kolors --prompt "赛博朋克城市夜景" --size 1280x720 --out city.png
```

> 生成图片下载到本地，stdout 给 `{out: <路径>, bytes, url}`。

### 8. asr — 语音转文字

```bash
node <SKILL_DIR>/scripts/sf.mjs asr --model <别名> --file <音频文件>
```

```bash
# 语音转写（SenseVoiceSmall，快、带情绪识别）
node <SKILL_DIR>/scripts/sf.mjs asr --model SenseVoiceSmall --file meeting.mp3

# 支持 mp3/wav/m4a/flac/ogg
node <SKILL_DIR>/scripts/sf.mjs asr --model SenseVoiceSmall --file record.wav
```

---

## 模型清单

| 类型 | 别名 | 完整 ID | 标记 | 说明 |
|---|---|---|---|---|
| 对话 | `GLM-4-9B-0414` | THUDM/GLM-4-9B-0414 | ⭐推荐 | 通用·性价比之王，快且准 |
| 对话 | `GLM-Z1-9B-0414` | THUDM/GLM-Z1-9B-0414 | 推理 | 推理型·中上，有思考链 |
| 对话 | `DeepSeek-R1-0528-Qwen3-8B` | deepseek-ai/… | 推理 | 推理型·严谨但慢 |
| 对话 | `Qwen3-8B` | Qwen/Qwen3-8B | 推理 | 推理型·稳但偏慢 |
| 对话 | `Qwen3.5-4B` | Qwen/Qwen3.5-4B | 推理 | 轻量推理（默认不传 max_tokens） |
| 对话 | `Qwen2.5-7B-Instruct` | Qwen/Qwen2.5-7B-Instruct | | 推理能力弱 |
| 翻译 | `Hunyuan-MT-7B` | tencent/Hunyuan-MT-7B | ⭐推荐 | 翻译专用，通用对话弱 |
| OCR | `DeepSeek-OCR` | deepseek-ai/DeepSeek-OCR | ⭐推荐 | 快准、自动 Markdown 表格 |
| OCR | `PaddleOCR-VL-1.5` | PaddlePaddle/PaddleOCR-VL-1.5 | | 可用但有幻觉风险 |
| 嵌入 | `bge-m3` | BAAI/bge-m3 | ⭐推荐 | 多语言/跨语言之王 |
| 嵌入 | `bge-large-zh-v1.5` | BAAI/bge-large-zh-v1.5 | | 中文区分度最佳 |
| 嵌入 | `bge-large-en-v1.5` | BAAI/bge-large-en-v1.5 | | 英文专精 |
| 重排 | `bge-reranker-v2-m3` | BAAI/bge-reranker-v2-m3 | ⭐推荐 | RAG 必备，精准区分实体歧义 |
| 生图 | `Kolors` | Kwai-Kolors/Kolors | ⭐推荐 | 国产优选，中文理解好 |
| 语音 | `SenseVoiceSmall` | FunAudioLLM/SenseVoiceSmall | ⭐推荐 | 快、规整、带情绪识别 |
| 语音 | `TeleSpeechASR` | TeleAI/TeleSpeechASR | | 基础可用，标点弱 |

---

## 参数说明

| 子命令 | 参数 | 必填 | 说明 |
|---|---|---|---|
| models | `--type` | 否 | 按类型过滤 |
| chat | `--model` | 是 | 模型别名或完整 ID |
| chat | `--prompt` | 是 | 用户提问 |
| chat | `--system` | 否 | 系统提示词 |
| chat | `--history` | 否 | 历史消息 JSON 文件（messages 数组） |
| chat | `--stream` | 否 | 流式传输（输出含 firstTokMs） |
| chat | `--max-tokens` | 否 | 默认不传（模型自定上限） |
| chat | `--temperature` | 否 | 采样温度 |
| translate | `--text` | 是 | 待翻译文本，可多个/@文件 |
| translate | `--source` | 否 | 源语言码，默认 `auto` 自动检测 |
| translate | `--target` | 否 | 目标语言码，默认 `zh` |
| translate | `--model` | 否 | 翻译模型，默认 Hunyuan-MT-7B |
| translate | `--max-tokens` | 否 | 限制译文长度 |
| ocr | `--model` | 是 | OCR 模型别名 |
| ocr | `--image` | 是 | 图片路径或 URL，可多个 |
| ocr | `--prompt` | 否 | 识别指令（默认识别全部文字） |
| embed | `--model` | 是 | 嵌入模型别名 |
| embed | `--input` | 是 | 文本或 @文件，可多个 |
| embed | `--save-vecs` | 否 | 向量保存路径（默认临时文件） |
| rerank | `--model` | 是 | 重排模型别名 |
| rerank | `--query` | 是 | 查询文本 |
| rerank | `--docs` | 是 | 文档（文本/@文件/a\|\|\|b），可多个 |
| rerank | `--top-n` | 否 | 返回前 N 条 |
| image | `--model` | 是 | 生图模型别名 |
| image | `--prompt` | 是 | 图片提示词 |
| image | `--size` | 否 | 尺寸，默认 1024x1024 |
| image | `--steps` | 否 | 推理步数 |
| image | `--out` | 否 | 输出文件（默认临时文件） |
| asr | `--model` | 是 | 语音模型别名 |
| asr | `--file` | 是 | 音频文件路径 |

---

## 错误码与诊断

| 场景 | 表现 | 处理 |
|---|---|---|
| API Key 未设置 | `{ok:false,error:"未设置环境变量 SILICONFLOW_API_KEY..."}` | 按上文获取章节设置环境变量后重开终端；Key 获取地址 https://cloud.siliconflow.cn/i/4xYXeAIS |
| API Key 无效 | HTTP 401 | 检查 Key 是否正确 |
| 模型不在免费范围 | HTTP 403 | 用 `models` 查可用模型 |
| 频率超限/额度用尽 | HTTP 429 | 稍后重试 |
| 模型名未识别 | `{ok:false,error:"未识别模型..."}` 列出候选 | 用候选别名重试 |
| 网络超时 | `AbortError: 请求超时` | 检查网络/代理 |
| 服务异常 | HTTP 5xx | 稍后重试 |
| 图片/音频不存在 | `{ok:false,error:"...文件不存在"}` | 检查路径 |

---

## 技术细节

- **API 端点**：`https://api.siliconflow.cn/v1`（OpenAI 兼容）
  - 对话/OCR：`/chat/completions`
  - 嵌入：`/embeddings`
  - 重排：`/rerank`
  - 生图：`/images/generations`
  - 语音：`/audio/transcriptions`（multipart/form-data）
- **认证**：`Authorization: Bearer $SILICONFLOW_API_KEY`
- **推理模型**：GLM-Z1-9B、DeepSeek-R1、Qwen3-8B、Qwen3.5-4B 返回 `reasoning_content`（思考链），脚本单独输出到 `reasoning` 字段
- **max_tokens 策略**：默认不传，让模型按自身上限输出（实测根除 Qwen3.5-4B 思考截断问题）；仅 `--max-tokens` 显式指定时才传
- **模型别名**：短名自动映射完整 ID，大小写不敏感；`models` 子命令可查全部
- **零依赖**：仅 Node.js 原生模块（`fs`/`path`/`os`/`fetch`），无需 `npm install`
- **跨平台**：用 `path.join`，纯 Node 模块，兼容 Windows/Linux/macOS

---

## 注意事项

1. **API Key 切勿硬编码**，统一用环境变量 `SILICONFLOW_API_KEY`。
2. **专用模型勿滥用**：翻译一律走 `translate` 子命令（Hunyuan-MT-7B 是翻译专用、通用推理弱，别当对话模型用）；SenseVoice 强项是情绪识别——按专长使用。
3. **OCR 首选 DeepSeek-OCR**：PaddleOCR-VL-1.5 有幻觉风险（会编造原图不存在内容），准确性要求高的场景勿用。
4. **推理模型速度代价**：DeepSeek-R1/Qwen3 思考链耗时 30-74s，实时性要求高请用 GLM-4-9B-0414（~1.4s）。
5. **嵌入向量**：默认写入系统临时文件，如需长期保留用 `--save-vecs` 指定路径。

---

## 参考资料

- **硅基流动免费模型性能测试页**：对 16 个免费模型做了可用性与质量横评（评分、耗时、实测证据、场景选型）→ https://u32.cn/zt/misc/2026/08/20260806200008-siliconflow-free-models-test/web/index.html

---

## 更新记录

### 0.2.0 (2026-08-12)
- 新增「参考资料」小节：硅基流动免费模型性能测试页
- 完善 API Key 获取说明：多平台命令行 + Windows GUI 手动步骤

License

No license was declared in this skill's source.

The full license text is available in the source repository.

View the license in the source repository — the version published there is authoritative.