@anionex/dsh-vision-toolkit 0.1.21 → 0.1.23

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write dsh-vision-toolkit/README.md
-README.md: 9de45ef4600013c30aa84bc0c959dabf9a7e5eb7
-README.zh.md: 21334a0caa949916aaa1c9f04babaca8ba8339b6
+README.md: b382c30dbb2676077ac95aaf67db7f809bc6fc15
+README.zh.md: a3504f000fa8baa161b2855f5cdf71b9584125f4

package/README.md

@@ -250,6 +250,8 @@ Existing clients that still send `api_key="free"` remain compatible.
 
 For higher quotas, private endpoints, or another model, change the provider in **Settings → Vision Toolkit** and store the API key as a DSH Credential. Settings stores the Credential reference and never reads the saved secret back into the browser.
 
+**Step-by-step Groq tutorial:** [Get a free Groq API key and use Qwen3.6-27B for image understanding](docs/groq-qwen3.6-vision.md). It includes screenshots for account/API-key setup, the exact Vision Toolkit settings, and working cURL and Python examples.
+
 You can also configure a Profile patch:
 
 ```yaml

package/README.zh.md

@@ -253,6 +253,8 @@ API Key:  https://agent-vision.anionex.me（自动填写）
 
 如果你需要更高额度、私有端点或其他模型，可以在 **设置 → 视觉工具** 中修改提供方，并把 API Key 保存为 DSH Credential。Settings 只保存 Credential 引用，不会回显密钥。
 
+**Groq 图文教程：** [免费获取 Groq API Key，并调用 Qwen3.6-27B 识图](docs/groq-qwen3.6-vision.zh.md)。教程包含账号与 API Key 获取截图、Vision Toolkit 的准确配置，以及可直接使用的 cURL 和 Python 示例。
+
 也可以在 Profile patch 中配置：
 
 ```yaml

package/docs/groq-qwen3.6-vision.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write dsh-vision-toolkit/docs/groq-qwen3.6-vision.md
+groq-qwen3.6-vision.md: 04907539da37edae3d9866007221403e8239516c
+groq-qwen3.6-vision.zh.md: 6fe5a22695efc3d90b937510b293c2e717cc6fd7

package/docs/groq-qwen3.6-vision.md

@@ -0,0 +1,236 @@
+# Get a free Groq API key and use Qwen3.6-27B for vision
+
+**English** | [中文](groq-qwen3.6-vision.zh.md)
+
+This guide covers two tasks:
+
+1. Sign up for the GroqCloud Free Plan and create a Groq API key.
+2. Use `qwen/qwen3.6-27b` to analyze images through DSH Vision Toolkit or ordinary code.
+
+> As of August 17, 2026, Groq lists Qwen3.6-27B as a Preview model with text and image input. Free Plan traffic is rate-limited and the limits can change; use the current [Groq Rate Limits](https://console.groq.com/docs/rate-limits) and [Qwen3.6-27B model page](https://console.groq.com/docs/model/qwen/qwen3.6-27b) as the source of truth.
+
+## 1. Create a free GroqCloud account
+
+Open the [GroqCloud Console](https://console.groq.com/). You can sign up or log in with Google, GitHub, SSO, or email.
+
+<p align="center">
+  <img src="assets/groq-console-home.png" width="92%" alt="GroqCloud Console sign-up and login page" />
+</p>
+
+The Free Plan is enough to complete this tutorial without purchasing paid capacity. It is not unlimited; the API returns `429 Too Many Requests` when the current quota is exhausted.
+
+As of August 17, 2026, the official Free Plan table lists Qwen3.6-27B at `30 RPM` (requests per minute), `1K RPD` (requests per day), `8K TPM` (tokens per minute), and `200K TPD` (tokens per day). Your organization's effective limits are shown on the Limits page in Groq Console.
+
+## 2. Create and save an API key
+
+After logging in, open **API Keys** in the top navigation or go directly to [Groq API Keys](https://console.groq.com/keys). When logged out, the page first shows this login prompt:
+
+<p align="center">
+  <img src="assets/groq-console-keys-login.png" width="92%" alt="Groq API Keys page asking the user to log in" />
+</p>
+
+On the API Keys page:
+
+1. Click **Create API Key**.
+2. Enter a recognizable name such as `dsh-vision-toolkit`.
+3. Confirm the creation.
+4. Copy the key beginning with `gsk_` immediately, then save it in a password manager or a DSH Credential.
+
+Groq's official Quickstart likewise starts with creating an API key and placing it in an environment variable:
+
+<p align="center">
+  <img src="assets/groq-docs-quickstart.png" width="88%" alt="Groq Quickstart instructions for creating and setting an API key" />
+</p>
+
+The complete API key is normally shown only once. Do not put it in a README, chat transcript, screenshot, Git commit, or frontend code.
+
+### Set the key in a terminal
+
+macOS / Linux:
+
+```sh
+export GROQ_API_KEY="gsk_your_key_here"
+```
+
+Windows PowerShell, for the current window:
+
+```powershell
+$env:GROQ_API_KEY = "gsk_your_key_here"
+```
+
+Confirm that the variable exists without printing the secret:
+
+```sh
+test -n "$GROQ_API_KEY" && echo "GROQ_API_KEY is set"
+```
+
+## 3. Confirm the model ID and vision support
+
+Use this exact model ID in Groq API requests:
+
+```text
+qwen/qwen3.6-27b
+```
+
+Do not shorten it to `qwen3.6-27b`, `Qwen3.6-27B`, or `27b`. The model page shows both image input and the Vision capability:
+
+<p align="center">
+  <img src="assets/groq-docs-qwen3.6.png" width="92%" alt="Groq Qwen3.6-27B model page showing image input and Vision capability" />
+</p>
+
+The Groq model page lists these main image limits:
+
+| Item | Limit |
+|---|---:|
+| Individual image file | 20 MB |
+| Images in one request | Up to 3 |
+
+Groq's general vision guide currently says that up to five images can be processed, while the Qwen3.6-27B model page says three. This guide follows the stricter model-specific limit to avoid rejected requests.
+
+<p align="center">
+  <img src="assets/groq-docs-vision.png" width="88%" alt="Groq Images and Vision documentation showing model limits and an image request example" />
+</p>
+
+## 4. Use it in DSH Vision Toolkit
+
+If this plugin is already installed, this is the shortest path.
+
+1. Open **Settings → Vision Toolkit** in DSH Web.
+2. Enter these values under Vision service:
+
+| Field | Value |
+|---|---|
+| API protocol | `OpenAI Chat Completions` |
+| Base URL | `https://api.groq.com/openai/v1` |
+| Model | `qwen/qwen3.6-27b` |
+| API key | Paste the newly created `gsk_...` key |
+
+3. Click **Save and apply**. The key is stored in DSH Credentials and its full value is not displayed again in Settings.
+4. Click **Test vision model**. This sends the plugin's bundled diagnostic image and verifies a real multimodal request rather than only checking `/models` connectivity.
+5. After the test succeeds, paste an image into a new or existing session and ask a focused question, for example:
+
+```text
+Inspect this screenshot. Transcribe the complete error first, then explain the most likely cause.
+```
+
+The same provider can be configured in a Profile patch. Keep the key in a DSH Credential or environment variable rather than writing it into YAML:
+
+```yaml
+- id: vision-toolkit
+  config:
+    provider:
+      protocol: openai
+      baseUrl: https://api.groq.com/openai/v1
+      model: qwen/qwen3.6-27b
+      credential: GROQ_API_KEY
+```
+
+## 5. Analyze a remote image with cURL
+
+The following request uses Groq's OpenAI Chat Completions-compatible endpoint. Replace the example URL with your own publicly accessible image URL:
+
+```sh
+curl https://api.groq.com/openai/v1/chat/completions \
+  -H "Authorization: Bearer $GROQ_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "qwen/qwen3.6-27b",
+    "messages": [{
+      "role": "user",
+      "content": [
+        {"type": "text", "text": "Describe the main content of this image and transcribe all visible text."},
+        {"type": "image_url", "image_url": {
+          "url": "https://upload.wikimedia.org/wikipedia/commons/f/f2/LPU-v1-die.jpg"
+        }}
+      ]
+    }],
+    "temperature": 0.2,
+    "max_completion_tokens": 1024
+  }'
+```
+
+The model's answer is returned at `choices[0].message.content`.
+
+## 6. Analyze a local image with Python
+
+This example reads a local image and converts it to a Base64 Data URL. Use `uv` to install the Groq SDK temporarily without modifying system Python:
+
+```python
+# recognize.py
+import base64
+import mimetypes
+from pathlib import Path
+
+from groq import Groq
+
+image_path = Path("screenshot.png")
+mime_type = mimetypes.guess_type(image_path.name)[0] or "image/png"
+image_base64 = base64.b64encode(image_path.read_bytes()).decode("ascii")
+data_url = f"data:{mime_type};base64,{image_base64}"
+
+client = Groq()  # Reads GROQ_API_KEY automatically.
+response = client.chat.completions.create(
+    model="qwen/qwen3.6-27b",
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "Analyze this screenshot: run OCR first, then identify the most important anomaly."},
+            {"type": "image_url", "image_url": {"url": data_url}},
+        ],
+    }],
+    temperature=0.2,
+    max_completion_tokens=1024,
+)
+
+print(response.choices[0].message.content)
+```
+
+Run it with:
+
+```sh
+uv run --with groq python recognize.py
+```
+
+Base64 makes the request larger than the original file. If the request approaches the 20 MB limit, resize or compress the image first, or use an HTTPS image URL that the model can access.
+
+## 7. Troubleshooting
+
+### `401 Invalid API Key`
+
+- Confirm that the entire `gsk_...` key was copied.
+- Do not include extra spaces, literal quote characters, or line breaks in the environment variable.
+- If the key was exposed publicly, delete it and create a replacement.
+
+### `404` or `model not found`
+
+- The model ID must be `qwen/qwen3.6-27b`.
+- The model is currently in Preview. If Groq changes its availability, check the official model page and the models currently shown in Groq Console.
+
+### `413` or an oversized image error
+
+- Base64 input has a lower size limit than URL input; resize or compress the image.
+- Do not place too many images in one request; the Qwen3.6-27B model page currently limits a request to three images.
+
+### `429 Too Many Requests`
+
+- The Free Plan has reached a per-minute, token, or daily limit.
+- Inspect the rate-limit response headers and retry after capacity resets.
+
+### The model describes the image but misses the task
+
+Make the request specific, for example:
+
+```text
+Do not give a generic description. Complete only these three tasks:
+1. Transcribe the text inside the red error box exactly;
+2. Report the error box's approximate location in the original image;
+3. Infer the most likely cause from the surrounding interface.
+```
+
+## Official references
+
+- [Groq Quickstart](https://console.groq.com/docs/quickstart)
+- [Groq API Keys](https://console.groq.com/keys)
+- [Qwen3.6-27B model page](https://console.groq.com/docs/model/qwen/qwen3.6-27b)
+- [Groq Images and Vision](https://console.groq.com/docs/vision)
+- [Groq Rate Limits](https://console.groq.com/docs/rate-limits)

package/docs/groq-qwen3.6-vision.zh.md

@@ -0,0 +1,236 @@
+# 免费获取 Groq API Key，并用 Qwen3.6-27B 识图
+
+[English](groq-qwen3.6-vision.md) | **中文**
+
+这篇教程完成两件事：
+
+1. 注册 GroqCloud 的 Free Plan，并创建一个 Groq API Key。
+2. 在 DSH Vision Toolkit 或普通代码中调用 `qwen/qwen3.6-27b` 分析图片。
+
+> 截至 2026-08-17，Groq 官方模型页将 Qwen3.6-27B 标记为 Preview，支持文本和图片输入。Free Plan 有速率和每日额度限制，具体数值可能调整，请以 [Groq Rate Limits](https://console.groq.com/docs/rate-limits) 和 [Qwen3.6-27B 模型页](https://console.groq.com/docs/model/qwen/qwen3.6-27b) 为准。
+
+## 1. 注册免费的 GroqCloud 账号
+
+打开 [GroqCloud Console](https://console.groq.com/)。可以使用 Google、GitHub、SSO 或邮箱注册/登录。
+
+<p align="center">
+  <img src="assets/groq-console-home.png" width="92%" alt="GroqCloud Console 登录和注册页面" />
+</p>
+
+完成注册后即可先使用 Free Plan，不需要为本教程购买付费额度。免费额度不是无限量服务；超出当前限制时，接口会返回 `429 Too Many Requests`。
+
+截至 2026-08-17，官方 Free Plan 表中 Qwen3.6-27B 的基础限制为 `30 RPM`（每分钟请求数）、`1K RPD`（每日请求数）、`8K TPM`（每分钟 Token 数）和 `200K TPD`（每日 Token 数）。账号的实际限制以 Groq Console 的 Limits 页面为准。
+
+## 2. 创建并保存 API Key
+
+登录后打开顶部的 **API Keys**，或直接访问 [Groq API Keys](https://console.groq.com/keys)。未登录时会先看到下面的登录页面：
+
+<p align="center">
+  <img src="assets/groq-console-keys-login.png" width="92%" alt="Groq API Keys 页面要求登录" />
+</p>
+
+在 API Keys 页面中：
+
+1. 点击 **Create API Key**。
+2. 给密钥填写一个容易辨认的名称，例如 `dsh-vision-toolkit`。
+3. 确认创建。
+4. 立即复制以 `gsk_` 开头的密钥，并保存到密码管理器或 DSH Credential 中。
+
+Groq 官方 Quickstart 也把“创建 API Key”和“通过环境变量保存密钥”放在最前面：
+
+<p align="center">
+  <img src="assets/groq-docs-quickstart.png" width="88%" alt="Groq Quickstart 中创建和设置 API Key 的说明" />
+</p>
+
+API Key 通常只在创建后完整显示一次。不要把它粘贴到 README、聊天记录、截图、Git 提交或前端代码中。
+
+### 在终端中设置密钥
+
+macOS / Linux：
+
+```sh
+export GROQ_API_KEY="gsk_your_key_here"
+```
+
+Windows PowerShell（只对当前窗口生效）：
+
+```powershell
+$env:GROQ_API_KEY = "gsk_your_key_here"
+```
+
+确认变量已经存在，但不要打印完整密钥：
+
+```sh
+test -n "$GROQ_API_KEY" && echo "GROQ_API_KEY is set"
+```
+
+## 3. 确认模型名和视觉能力
+
+Groq API 中必须使用完整模型 ID：
+
+```text
+qwen/qwen3.6-27b
+```
+
+不要写成 `qwen3.6-27b`、`Qwen3.6-27B` 或只写 `27b`。模型页会同时显示图片输入和 Vision 能力：
+
+<p align="center">
+  <img src="assets/groq-docs-qwen3.6.png" width="92%" alt="Groq Qwen3.6-27B 模型页显示文本和图片输入及 Vision 能力" />
+</p>
+
+Groq 模型页列出的主要图片限制是：
+
+| 项目 | 限制 |
+|---|---:|
+| 单个图片文件 | 最大 20 MB |
+| 单次请求图片数 | 最多 3 张 |
+
+Groq 的通用视觉文档当前写的是最多 5 张图片，但 Qwen3.6-27B 的模型专页写的是最多 3 张。这里按模型专页的更严格限制执行，避免请求被拒绝。
+
+<p align="center">
+  <img src="assets/groq-docs-vision.png" width="88%" alt="Groq Images and Vision 文档中的模型、限制和图片调用示例" />
+</p>
+
+## 4. 在 DSH Vision Toolkit 中使用
+
+如果已经安装本插件，这是最短路径。
+
+1. 打开 DSH Web 的 **设置 → 视觉工具**。
+2. 在“视觉服务”中填写：
+
+| 字段 | 值 |
+|---|---|
+| API 协议 | `OpenAI Chat Completions` |
+| 服务地址 | `https://api.groq.com/openai/v1` |
+| 模型名称 | `qwen/qwen3.6-27b` |
+| API 密钥 | 粘贴刚创建的 `gsk_...` 密钥 |
+
+3. 点击 **保存并应用**。密钥会保存到 DSH Credentials，设置页面以后不会回显完整内容。
+4. 点击 **测试视觉模型**。这个按钮会发送插件自带的诊断图片，验证的是真实多模态请求，而不只是 `/models` 连通性。
+5. 测试成功后，新建或继续一个会话，粘贴图片并直接提问，例如：
+
+```text
+看一下这张截图，先完整抄出报错信息，再解释最可能的原因。
+```
+
+也可以在 Profile patch 中配置相同的提供方。密钥本身仍应由 DSH Credential 或环境变量提供，不要写进 YAML：
+
+```yaml
+- id: vision-toolkit
+  config:
+    provider:
+      protocol: openai
+      baseUrl: https://api.groq.com/openai/v1
+      model: qwen/qwen3.6-27b
+      credential: GROQ_API_KEY
+```
+
+## 5. 用 cURL 直接识别网络图片
+
+下面的请求使用 Groq 的 OpenAI Chat Completions 兼容接口。把示例图片 URL 换成你自己的公开图片地址：
+
+```sh
+curl https://api.groq.com/openai/v1/chat/completions \
+  -H "Authorization: Bearer $GROQ_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "qwen/qwen3.6-27b",
+    "messages": [{
+      "role": "user",
+      "content": [
+        {"type": "text", "text": "请描述图片中的主要内容，并逐字抄出可见文字。"},
+        {"type": "image_url", "image_url": {
+          "url": "https://upload.wikimedia.org/wikipedia/commons/f/f2/LPU-v1-die.jpg"
+        }}
+      ]
+    }],
+    "temperature": 0.2,
+    "max_completion_tokens": 1024
+  }'
+```
+
+成功后，模型回答位于 `choices[0].message.content`。
+
+## 6. 用 Python 识别本地图片
+
+下面的例子读取本地图片并转换成 Base64 Data URL。推荐使用 `uv` 临时安装 Groq SDK，不污染系统 Python：
+
+```python
+# recognize.py
+import base64
+import mimetypes
+from pathlib import Path
+
+from groq import Groq
+
+image_path = Path("screenshot.png")
+mime_type = mimetypes.guess_type(image_path.name)[0] or "image/png"
+image_base64 = base64.b64encode(image_path.read_bytes()).decode("ascii")
+data_url = f"data:{mime_type};base64,{image_base64}"
+
+client = Groq()  # 自动读取 GROQ_API_KEY
+response = client.chat.completions.create(
+    model="qwen/qwen3.6-27b",
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "分析这张截图：先做 OCR，再指出最重要的异常。"},
+            {"type": "image_url", "image_url": {"url": data_url}},
+        ],
+    }],
+    temperature=0.2,
+    max_completion_tokens=1024,
+)
+
+print(response.choices[0].message.content)
+```
+
+运行：
+
+```sh
+uv run --with groq python recognize.py
+```
+
+Base64 会让请求体积比原文件更大。如果请求接近 20 MB 上限，请先缩小或压缩图片，或者改用模型能够访问的 HTTPS 图片 URL。
+
+## 7. 常见问题
+
+### `401 Invalid API Key`
+
+- 确认复制的是完整的 `gsk_...` 密钥。
+- 环境变量中不要包含多余空格、引号内容或换行。
+- 如果密钥曾经出现在公开位置，删除旧密钥并重新创建。
+
+### `404` 或 `model not found`
+
+- 模型名必须是 `qwen/qwen3.6-27b`。
+- 该模型目前属于 Preview；如果 Groq 后续调整可用性，请查看官方模型页和 Groq Console 中当前可选模型。
+
+### `413` 或图片过大
+
+- Base64 图片限制比 URL 图片严格；先缩小尺寸或压缩质量。
+- 不要把大量图片塞进一个请求；按 Qwen3.6-27B 模型专页的限制，单次最多 3 张。
+
+### `429 Too Many Requests`
+
+- Free Plan 已达到分钟、Token 或每日限制。
+- 查看响应头中的速率限制信息，等待额度恢复后重试。
+
+### 模型只描述图片，没有回答重点
+
+把任务写具体，例如：
+
+```text
+不要泛泛描述。请只完成三件事：
+1. 逐字抄出红色错误框里的文字；
+2. 返回错误框在原图中的大致位置；
+3. 根据界面上下文判断最可能的原因。
+```
+
+## 官方资料
+
+- [Groq Quickstart](https://console.groq.com/docs/quickstart)
+- [Groq API Keys](https://console.groq.com/keys)
+- [Qwen3.6-27B 模型页](https://console.groq.com/docs/model/qwen/qwen3.6-27b)
+- [Groq Images and Vision](https://console.groq.com/docs/vision)
+- [Groq Rate Limits](https://console.groq.com/docs/rate-limits)