SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场qwencloud-text

qwencloud-text

通用与其它

查看项目

更新于 10-16 08:19

技能介绍

用途

qwencloud-text 用于通过 OpenAI 兼容接口调用 QwenCloud 上的 Qwen 模型与第三方模型，完成文本生成、多轮对话、代码编写、推理以及函数调用等任务。该技能是 qwencloud/qwencloud-ai 技能集的一部分。

主要能力

  • 文本生成与对话：通过 chat/completions 请求生成内容，支持 system 提示词、temperature、max_tokens 等参数。
  • 流式输出：通过 --stream 启用，适合交互式使用。
  • 结构化输出：通过 response_format 指定 json_schema，强制输出符合模式的 JSON。
  • 联网搜索：通过 enable_search: true 获取实时的联网增强回答。
  • 深度思考：通过 enable_thinking: true 启用扩展推理，仅在用户要求时使用。
  • 函数调用：通过 tools 字段定义函数，支持工具调用。
  • 上下文缓存：对重复前缀自动生效，或使用基于会话的显式方式，降低重复上下文的成本。
  • 前缀续写：通过 partial_mode: "prefix" 续写或补全前缀。
  • 批量推理：异步批量 API，采用 JSONL 输入，据资料为 50% 成本折扣。

以上功能均通过同一个 chat/completions 端点提供，详细用法见 api-guide.md 与 sources.md。

使用方式

前提条件：

  • API 密钥：依次检查 QWENCLOUD_API_KEY、QWEN_API_KEY、DASHSCOPE_API_KEY，仅做非明文检查（只报告“已设置”或“未设置”，绝不显示密钥值）。若未设置，可在有 qwencloud-ops-auth 技能时运行该技能，否则从 QwenCloud 控制台获取密钥，并通过 .env 文件（echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env）或环境变量设置。脚本会在当前工作目录与项目根目录自动加载 .env。
  • Python 3.9+：脚本仅使用标准库，无需 pip 安装。执行前可用 python3 --version 检查，若找不到 python3 可尝试 python 或 py -3。

默认执行方式：脚本位于本技能目录的 scripts/ 子目录下，需先定位技能安装目录，并使用完整绝对路径执行，不要假定脚本在当前工作目录，也不要先 cd 切换目录。所有脚本在前台运行并等待 stdout。可先运行 python3 <this-skill-dir>/scripts/text.py --help 查看全部参数。

示例（非流式）：

python3 <this-skill-dir>/scripts/text.py
--request '{"messages":[{"role":"user","content":"Hello!"}],"model":"qwen3.7-plus"}'
--output output/qwencloud-text/ --print-response

示例（流式）：

python3 <this-skill-dir>/scripts/text.py
--request '{"messages":[{"role":"user","content":"Write a poem about the sea"}],"model":"qwen3.7-plus"}'
--stream --print-response

主要参数：

  • --request '{...}'：JSON 请求体
  • --file path.json：从文件加载请求（替代 --request）
  • --stream：启用流式输出
  • --output path：保存响应 JSON 到指定路径（.json 后缀为文件，否则为目录）；多次调用需使用不同文件名以避免覆盖
  • --print-response：将响应打印到 stdout
  • --model ID：覆盖模型（也可在请求 JSON 中设置）

验证结果：退出码 0 且输出包含带 choices 字段的有效 JSON 即成功；非零退出、HTTP 错误、空响应或含 "code"/"message" 错误的 JSON 即失败。若无法读取退出码，可扫描输出中的错误模式（Error、Traceback、401、403）。使用 --output 后需确认响应 JSON 文件存在且包含 choices。

输出位置：优先使用当前工作目录，使用 --output 时默认子目录为 ./output/qwencloud-text/。禁止将输出文件写入本技能安装目录或任何 skills/ 层级，生成内容必须写入当前工作目录下的 output/ 或用户指定路径。

适用场景

  • 需要以 OpenAI 兼容方式调用 Qwen 模型或第三方模型完成文本任务。
  • 需要流式交互式对话、代码生成、推理或函数调用。
  • 需要结构化 JSON 输出、联网搜索增强、深度思考、前缀续写或批量推理。
  • 使用 Token Plan 密钥（sk-sp-…）时自动路由到 Token Plan 端点（token-plan.ap-southeast-1.maas.aliyuncs.com）。

限制与注意事项

  • 禁止覆盖用户指定的参数：若用户明确指定模型，必须严格使用该模型，不得替换、添加未要求的参数或进行“优化”。只有在用户未指定模型时，才参考模型目录或 qwencloud-model-selector 技能进行选择。
  • 模型目录为某一时点的快照，可能过期，模型可用性变化频繁，应以官方模型列表为准。
  • 密钥安全：绝不能以明文输出任何 API 密钥或凭据；任何凭据检查必须非明文，只报告状态（如“已设置”/“未设置”、“有效”/“无效”）。密钥未配置时，不得直接要求用户提供密钥，而应帮助创建含占位符的 .env 文件，并指导用户替换为实际密钥；仅当用户明确要求时才写入真实密钥值。不得显示可能含密钥的 .env 或配置文件内容。
  • Coding Plan 密钥（同为 sk-sp- 前缀但通过 Coding Plan 订阅购买）仅用于交互式编程工具，在这些脚本上会失败。
  • Token Plan 不使用 curl，始终使用随附的 Python 脚本。
  • 错误处理：401 为密钥无效或缺失；429 为限流，需退避重试；5xx 为服务端错误，需重试并检查状态页；无效模型需对照模型目录核对 ID；无效参数需校验 JSON 与字段类型；TypeError: ...proxies 为 openai SDK 与 httpx 不兼容，可升级 openai（>=1.55.0）或改用纯标准库脚本。若 SSL 证书失败，macOS 可运行 Install Certificates.command，否则设置 SSL_CERT_FILE 环境变量；网络不可达时检查网络并设置 HTTPS_PROXY。
  • 更新检查（强制执行）：脚本执行后必须检查 stderr 中的 [ACTION_REQUIRED] 或 [UPDATE_AVAILABLE] 信号。若出现 [ACTION_REQUIRED]（未安装 qwencloud-update-check 技能），必须向用户呈现安装、暂时跳过、永久不再提醒三个选项，等待用户回应后再继续，不得静默跳过。用户选择 1 时运行 npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -y，随后运行 python3 <this-skill-scripts-dir>/gossamer.py --dismiss；选择 2 时运行 python3 <this-skill-scripts-dir>/gossamer.py --dismiss；选择 3 时运行 python3 <this-skill-scripts-dir>/gossamer.py --never-install。若出现 [UPDATE_AVAILABLE]，必须在回复中附加简要更新提示，含版本信息与 stderr 中给出的更新命令。若 stderr 无信号则无需操作。
  • 用量与计费：可通过 qwencloud-usage 技能查询用量、免费额度与计费，或访问 QwenCloud 控制台。不得编造、猜测或构造用量/计费/控制台 URL，仅可提供本技能列出的确切链接。
  • 本资料未提供具体定价、免费额度数值、模型完整清单及第三方模型明细，如需请查询官方渠道。