mirror of
https://github.com/modelstudioai/skills.git
synced 2026-09-19 04:50:42 +08:00
chore: update bailian-docs-llm-wiki (2026-07-30)
This commit is contained in:
gujieye
File diff suppressed because it is too large
Load Diff
@@ -24,7 +24,9 @@
|
||||
{"slug":"fun-music","name":"音乐生成","description":"百聆音乐生成大模型（Fun音乐大模型）支持输入开放性歌曲的创作要求或歌词，生成整首男/女声演唱的中文或英文歌曲。歌曲通俗易懂，情绪由浅入深，是人类灵感与大模型能力的完美结合。","primaryCapability":"TTS","capabilities":["TTS"],"providers":["qwen"],"itemCount":2,"items":[{"model":"fun-music-preview","name":"音乐生成 Preview","capabilities":["TTS"]},{"model":"fun-music-v1","name":"音乐生成","capabilities":["TTS"]}],"detailPath":"groups/fun-music.json"}
|
||||
{"slug":"glm-4.5","name":"GLM","description":"GLM是由智谱提供的开源模型。","primaryCapability":"TG","capabilities":["TG","Reasoning"],"providers":["zhipu-ai"],"itemCount":7,"items":[{"model":"glm-4.5","name":"GLM-4.5","contextWindow":131072,"capabilities":["TG"]},{"model":"glm-4.5-air","name":"GLM-4.5-Air","contextWindow":131072,"capabilities":["TG"]},{"model":"glm-4.6","name":"GLM-4.6","contextWindow":202752,"capabilities":["Reasoning","TG"]},{"model":"glm-4.7","name":"GLM-4.7","contextWindow":202752,"capabilities":["TG","Reasoning"]},{"model":"glm-5","name":"GLM-5","contextWindow":202752,"capabilities":["TG","Reasoning"]},{"model":"glm-5.1","name":"GLM-5.1","contextWindow":202745,"capabilities":["TG","Reasoning"]},{"model":"glm-5.2","name":"GLM-5.2","contextWindow":1048576,"capabilities":["TG","Reasoning"]}],"detailPath":"groups/glm-4.5.json","maxContextWindow":1048576}
|
||||
{"slug":"glm-fast","name":"GLM-5.2-Fast","description":"GLM-5.2-Fast-Preview 是智谱 AI 旗舰模型 GLM-5.2 的高速版本，支持 1M 超长上下文，模型能力对齐 GLM-5.2 标准版，具备逻辑推理、长文本理解与代码生成能力。通过推理加速优化，输出 TPS 可达 GLM-5.2 标准版的 1.5～2 倍，显著提升输出速度，适用于实时对话、Agent 多轮调用、流式代码生成等对输出速度敏感的场景。","primaryCapability":"TG","capabilities":["TG"],"providers":["zhipu-ai"],"itemCount":1,"items":[{"model":"glm-5.2-fast-preview","name":"GLM-5.2-Fast-Preview","contextWindow":1048576,"capabilities":["TG"]}],"detailPath":"groups/glm-fast.json","maxContextWindow":1048576}
|
||||
{"slug":"gui-plus","name":"GUI-Plus","description":"GUI系列图形界面交互基础模型，针对手机端与电脑端图形界面理解与交互任务，性能优于开源版同类GUI模型。全面升级跨平台界面理解与多步任务规划，支持跨应用复杂任务；具备精细化动作执行与多角色多智能体协作能力，胜任真实复杂交互场景。","primaryCapability":"VU","capabilities":["VU"],"providers":["qwen-domain-model"],"itemCount":1,"items":[{"model":"gui-plus","name":"GUI-Plus","contextWindow":256000,"capabilities":["VU"]}],"detailPath":"groups/gui-plus.json","maxContextWindow":256000}
|
||||
{"slug":"gummy-chat-v1","name":"一句话识别及翻译V1.0","description":"多语言语音转写及翻译的多模态大模型。本模型支持60秒以内的实时语音识别，适用于语音搜索、设备指令等场景。提供10个混合语种的高准确率识别服务，同时支持中英日韩互译，以其他6个语种翻译成中文或英文。","primaryCapability":"ASR","capabilities":["ASR"],"providers":["qwen"],"itemCount":1,"items":[{"model":"gummy-chat-v1","name":"一句话识别及翻译V1.0","capabilities":["ASR"]}],"detailPath":"groups/gummy-chat-v1.json"}
|
||||
{"slug":"gummy-realtime-v1","name":"实时语音识别及翻译V1.0","description":"多语言语音转写及翻译的多模态大模型。本模型提供长时间、高准确率、实时转写中/英/日/韩等10个混合语种的服务。同时支持中英日韩互译，以其他6个语种翻译成中文或英文。","primaryCapability":"Realtime-Audio-Translate","capabilities":["Realtime-Audio-Translate"],"providers":["qwen"],"itemCount":1,"items":[{"model":"gummy-realtime-v1","name":"实时语音识别及翻译V1.0","capabilities":["Realtime-Audio-Translate"]}],"detailPath":"groups/gummy-realtime-v1.json"}
|
||||
{"slug":"happyhorse-i2v","name":"HappyHorse-I2V","description":"HappyHorse系列最新图生视频模型，具备高度还原的动态画面生成能力，能够稳定保持与图像一致性，输出流畅自然、细节丰富的高质量视频。","primaryCapability":"VG","capabilities":["VG"],"providers":["happyhorse"],"itemCount":2,"items":[{"model":"happyhorse-1.0-i2v","name":"HappyHorse-1.0-I2V","capabilities":["VG"]},{"model":"happyhorse-1.1-i2v","name":"HappyHorse-1.1-I2V","capabilities":["VG"]}],"detailPath":"groups/happyhorse-i2v.json"}
|
||||
{"slug":"happyhorse-r2v","name":"HappyHorse-R2V","description":"HappyHorse-R2V支持参考生视频，更加稳定的主体与场景参考，支持最多9张图片参考，能够精准保持创作意图，实现更强表现能力。","primaryCapability":"VG","capabilities":["VG"],"providers":["happyhorse"],"itemCount":2,"items":[{"model":"happyhorse-1.0-r2v","name":"HappyHorse-1.0-R2V","capabilities":["VG"]},{"model":"happyhorse-1.1-r2v","name":"HappyHorse-1.1-R2V","capabilities":["VG"]}],"detailPath":"groups/happyhorse-r2v.json"}
|
||||
{"slug":"happyhorse-t2v","name":"HappyHorse-T2V","description":"HappyHorse系列最新文生视频模型，具备高度还原的动态画面生成能力，能够精准理解文本语义，输出流畅自然、细节丰富的高质量视频。","primaryCapability":"VG","capabilities":["VG"],"providers":["happyhorse"],"itemCount":2,"items":[{"model":"happyhorse-1.0-t2v","name":"HappyHorse-1.0-T2V","capabilities":["VG"]},{"model":"happyhorse-1.1-t2v","name":"HappyHorse-1.1-T2V","capabilities":["VG"]}],"detailPath":"groups/happyhorse-t2v.json"}
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,68 @@
|
||||
{
|
||||
"name": "实时语音识别及翻译V1.0",
|
||||
"description": "多语言语音转写及翻译的多模态大模型。本模型提供长时间、高准确率、实时转写中/英/日/韩等10个混合语种的服务。同时支持中英日韩互译，以其他6个语种翻译成中文或英文。",
|
||||
"items": [
|
||||
{
|
||||
"inferenceMetadata": {
|
||||
"response_modality": [
|
||||
"Text"
|
||||
],
|
||||
"request_modality": [
|
||||
"Audio"
|
||||
]
|
||||
},
|
||||
"description": "多语言语音转写及翻译的多模态大模型。本模型提供长时间、高准确率、实时转写中/英/日/韩等10个混合语种的服务。同时支持中英日韩互译，以其他6个语种翻译成中文或英文。",
|
||||
"features": [
|
||||
"model-experience"
|
||||
],
|
||||
"provider": "qwen",
|
||||
"model": "gummy-realtime-v1",
|
||||
"prices": [
|
||||
{
|
||||
"priceUnit": "每秒",
|
||||
"price": "0.00015",
|
||||
"timeBand": "standard",
|
||||
"type": "content_duration",
|
||||
"priceName": "音频时长"
|
||||
}
|
||||
],
|
||||
"qpmInfo": {
|
||||
"model-default-actual": {
|
||||
"count_limit_period": 1,
|
||||
"count_limit": 10,
|
||||
"type": "model-default"
|
||||
},
|
||||
"model-default": {
|
||||
"count_limit_period": 1,
|
||||
"count_limit": 10,
|
||||
"type": "model-default"
|
||||
}
|
||||
},
|
||||
"priceTimeBands": [
|
||||
"standard"
|
||||
],
|
||||
"capabilities": [
|
||||
"Realtime-Audio-Translate"
|
||||
],
|
||||
"versionTag": "MAJOR",
|
||||
"latestOnlineAt": "2025-03-04T04:07:10.000+00:00",
|
||||
"offlineInfo": {
|
||||
"inference": {
|
||||
"announceUrl": "https://www.aliyun.com/notice/118331",
|
||||
"offlineTime": "2026-10-10 00:00:00"
|
||||
}
|
||||
},
|
||||
"inferenceProvider": "aliyun-bailian",
|
||||
"name": "实时语音识别及翻译V1.0",
|
||||
"docUrl": "https://help.aliyun.com/document_detail/2865393.html",
|
||||
"samples": {
|
||||
"dashscope": {
|
||||
"default": {
|
||||
"python": "import requests\nfrom http import HTTPStatus\n\nimport dashscope\nfrom dashscope.audio.asr import *\n\n# 若没有将API Key配置到环境变量中，需将your-api-key替换为自己的API Key\n# dashscope.api_key = \"your-api-key\"\n\nr = requests.get(\n \"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav\"\n)\nwith open(\"asr_example.wav\", \"wb\") as f:\n f.write(r.content)\n\ntranslator = TranslationRecognizerRealtime(\n model=\"gummy-realtime-v1\",\n format=\"wav\",\n sample_rate=16000,\n translation_target_languages=[\"en\"],\n translation_enabled=True,\n callback=None,\n)\nresult = translator.call(\"asr_example.wav\")\nif not result.error_message:\n print(\"request id: \", result.request_id)\n print(\"transcription: \")\n for transcription_result in result.transcription_result_list:\n print(transcription_result.text)\n print(\"translation[en]: \")\n\n for translation_result in result.translation_result_list:\n print(translation_result.get_translation('en').text)\nelse:\n print(\"Error: \", result.error_message)",
|
||||
"java": "import com.alibaba.dashscope.audio.asr.translation.TranslationRecognizerParam;\nimport com.alibaba.dashscope.audio.asr.translation.TranslationRecognizerRealtime;\nimport com.alibaba.dashscope.audio.asr.translation.results.TranscriptionResult;\nimport com.alibaba.dashscope.audio.asr.translation.results.TranslationRecognizerResultPack;\nimport com.alibaba.dashscope.audio.asr.translation.results.TranslationResult;\n\nimport java.io.File;\nimport java.util.ArrayList;\n\npublic class Main {\n\n public static void main(String[] args) {\n String targetLanguage = \"en\";\n // 创建Recognition实例\n TranslationRecognizerRealtime translator = new TranslationRecognizerRealtime();\n // 创建RecognitionParam，请在实际使用中替换真实apiKey\n TranslationRecognizerParam param =\n TranslationRecognizerParam.builder()\n // 若没有将API Key配置到环境变量中，需将下面这行代码注释放开，并将your-api-key替换为自己的API Key\n // .apiKey(\"your-api-key\")\n .model(\"gummy-realtime-v1\")\n .format(\"wav\") // 'pcm'、'wav'、'mp3'、'opus'、'speex'、'aac'、'amr', you\n // can check the supported formats in the document\n .sampleRate(16000)\n .transcriptionEnabled(true)\n .sourceLanguage(\"auto\")\n .translationEnabled(true)\n .translationLanguages(new String[] {targetLanguage})\n .build();\n // 直接将结果保存到script.txt中\n TranslationRecognizerResultPack result = translator.call(param, new File(\"hello_world.wav\"));\n // 任务结束后关闭 websocket 连接\n translator.getDuplexApi().close(1000, \"bye\");\n if (result.getError() != null) {\n System.out.println(\"error: \" + result.getError());\n throw new RuntimeException(result.getError());\n } else {\n System.out.println(\"RequestId: \" + result.getRequestId());\n System.out.println(\"Transcription Results:\");\n ArrayList<TranscriptionResult> transcriptionResults = result.getTranscriptionResultList();\n for (int i = 0; i < transcriptionResults.size(); i++) {\n System.out.println(transcriptionResults.get(i).getText());\n }\n\n System.out.println(\"English Translation Results:\");\n ArrayList<TranslationResult> translationResultList = result.getTranslationResultList();\n for (int i = 0; i < translationResultList.size(); i++) {\n System.out.println(translationResultList.get(i).getTranslation(targetLanguage).getText());\n }\n }\n System.exit(0);\n }\n}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"updatedAt": "2026-07-30",
|
||||
"totalFamilies": 170,
|
||||
"totalModels": 387,
|
||||
"totalFamilies": 172,
|
||||
"totalModels": 389,
|
||||
"capabilityDistribution": {
|
||||
"TG": 36,
|
||||
"IG": 31,
|
||||
@@ -9,20 +9,20 @@
|
||||
"TTS": 16,
|
||||
"Reasoning": 14,
|
||||
"ASR": 12,
|
||||
"VU": 8,
|
||||
"VU": 9,
|
||||
"Realtime-ASR": 7,
|
||||
"Multimodal-Omni": 5,
|
||||
"Realtime-Omni": 4,
|
||||
"Realtime-Audio-Translate": 3,
|
||||
"ME": 2,
|
||||
"Realtime-Chatting": 2,
|
||||
"Realtime-Text-to-Speech": 2,
|
||||
"TR": 2,
|
||||
"Realtime-Audio-Translate": 2,
|
||||
"3D-generation": 1
|
||||
},
|
||||
"providerDistribution": {
|
||||
"qwen": 102,
|
||||
"qwen-domain-model": 33,
|
||||
"qwen": 103,
|
||||
"qwen-domain-model": 34,
|
||||
"wan": 13,
|
||||
"happyhorse": 4,
|
||||
"pixverse": 4,
|
||||
@@ -475,6 +475,22 @@
|
||||
],
|
||||
"maxContextWindow": 1048576
|
||||
},
|
||||
{
|
||||
"slug": "gui-plus",
|
||||
"name": "GUI-Plus",
|
||||
"primaryCapability": "VU",
|
||||
"capabilities": [
|
||||
"VU"
|
||||
],
|
||||
"providers": [
|
||||
"qwen-domain-model"
|
||||
],
|
||||
"itemCount": 1,
|
||||
"items": [
|
||||
"gui-plus"
|
||||
],
|
||||
"maxContextWindow": 256000
|
||||
},
|
||||
{
|
||||
"slug": "gummy-chat-v1",
|
||||
"name": "一句话识别及翻译V1.0",
|
||||
@@ -490,6 +506,21 @@
|
||||
"gummy-chat-v1"
|
||||
]
|
||||
},
|
||||
{
|
||||
"slug": "gummy-realtime-v1",
|
||||
"name": "实时语音识别及翻译V1.0",
|
||||
"primaryCapability": "Realtime-Audio-Translate",
|
||||
"capabilities": [
|
||||
"Realtime-Audio-Translate"
|
||||
],
|
||||
"providers": [
|
||||
"qwen"
|
||||
],
|
||||
"itemCount": 1,
|
||||
"items": [
|
||||
"gummy-realtime-v1"
|
||||
]
|
||||
},
|
||||
{
|
||||
"slug": "happyhorse-i2v",
|
||||
"name": "HappyHorse-I2V",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 百炼模型市场索引
|
||||
|
||||
> 自动生成 · 共 170 个模型家族 · 387 个主干模型 · 更新于 2026-07-30
|
||||
> 自动生成 · 共 172 个模型家族 · 389 个主干模型 · 更新于 2026-07-30
|
||||
|
||||
**机器查询走结构化文件**：
|
||||
|
||||
@@ -299,8 +299,10 @@ join：`models.jsonl[].family == families.jsonl[].slug == index.json.families[].
|
||||
- [语音识别热词](groups/speech-biasing.json) — 热词是指用户可以预先定义的一组特定词汇或短语，这些词汇或短语在识别、翻译过程中会被赋予更高的优先级。针对您的特定业务领域，如果有部分词汇的语音识别、翻译效果不够好，可以将这些关键词或短语添加为热词进行…
|
||||
- 模型：`speech-biasing`
|
||||
|
||||
## 视觉理解 `VU` — 8 个家族
|
||||
## 视觉理解 `VU` — 9 个家族
|
||||
|
||||
- [GUI-Plus](groups/gui-plus.json) — GUI系列图形界面交互基础模型，针对手机端与电脑端图形界面理解与交互任务，性能优于开源版同类GUI模型。全面升级跨平台界面理解与多步任务规划，支持跨应用复杂任务；具备精细化动作执行与多角色多智能体协作…
|
||||
- 模型：`gui-plus`
|
||||
- [Qwen-VL-Max](groups/qwen-vl-max.json) — Qwen-VL-Max，即千问超大规模视觉语言模型。相比增强版，再次提升视觉推理能力和指令遵循能力，提供更高的视觉感知和认知水平。在更多复杂任务上提供最佳的性能。
|
||||
- 模型：`qwen-vl-max`
|
||||
- [Qwen-VL-OCR](groups/qwen-vl-ocr.json) — Qwen-VL-OCR，即基于Qwen-VL训练的OCR识别大模型。通过统一模型的方式聚合多种图文识别、解析、处理类任务，提供强大的图文识别能力。
|
||||
@@ -359,6 +361,15 @@ join：`models.jsonl[].family == families.jsonl[].slug == index.json.families[].
|
||||
- [Qwen3.5-Omni-Plus-Realtime](groups/qwen3.5-omni-plus-realtime.json) — Qwen3.5-Omni是Qwen最新一代全模态大模型，支持文本，图片，音频，音视频理解与交互。作为 Qwen3-Omni 的全面进化版本，支持60+种语言音频输入，30+语言语音输出以及可控语音对话…
|
||||
- 模型：`qwen3.5-omni-plus-realtime`
|
||||
|
||||
## 实时音频翻译 `Realtime-Audio-Translate` — 3 个家族
|
||||
|
||||
- [Qwen3-LiveTranslate-Flash-Realtime](groups/qwen3-livetranslate-flash-realtime.json) — Qwen3-LiveTranslate-Flash-Realtime的实时版本，一款高精度、高响应、高鲁棒性的多语言实时音视频同传大模型。依托Qwen3-Omni强大的基座能力、海量多模态数据、跨语言…
|
||||
- 模型：`qwen3-livetranslate-flash-realtime`
|
||||
- [Qwen3.5-LiveTranslate-Flash-Realtime](groups/qwen3.5-livetranslate-flash-realtime.json) — Qwen3.5-LiveTranslate-Flash的实时版本，一款高精度、高响应、高鲁棒性的多语言实时音视频同传大模型。依托Qwen3.5-Omni强大的基座能力、海量多模态数据、跨语言跨模态对齐…
|
||||
- 模型：`qwen3.5-livetranslate-flash-realtime`
|
||||
- [实时语音识别及翻译V1.0](groups/gummy-realtime-v1.json) — 多语言语音转写及翻译的多模态大模型。本模型提供长时间、高准确率、实时转写中/英/日/韩等10个混合语种的服务。同时支持中英日韩互译，以其他6个语种翻译成中文或英文。
|
||||
- 模型：`gummy-realtime-v1`
|
||||
|
||||
## 多模态嵌入 `ME` — 2 个家族
|
||||
|
||||
- [Qwen-VL-Embedding](groups/qwen-vl-embedding.json) — 基于Qwen-VL底座训练的统一多模态向量模型，支持文本、图片、视频单模态/混合模态输入，输出统一表征向量，适用于跨模态检索、图搜、视频检索、图像聚类、复杂多模态信息检索、打标等场景。
|
||||
@@ -387,13 +398,6 @@ join：`models.jsonl[].family == families.jsonl[].slug == index.json.families[].
|
||||
- [Qwen-Rerank](groups/qwen-rerank.json) — 基于Qwen LLM底座训练的文本排序模型，对输入的Query和候选Docs进行相关性排序，支持100+语种和长文本输入，适用于文本检索、RAG等场景，效果对齐Qwen家族开源Rerank系列模型。
|
||||
- 模型：`gte-rerank-v2`, `qwen3-rerank`, `qwen3-vl-rerank`
|
||||
|
||||
## 实时音频翻译 `Realtime-Audio-Translate` — 2 个家族
|
||||
|
||||
- [Qwen3-LiveTranslate-Flash-Realtime](groups/qwen3-livetranslate-flash-realtime.json) — Qwen3-LiveTranslate-Flash-Realtime的实时版本，一款高精度、高响应、高鲁棒性的多语言实时音视频同传大模型。依托Qwen3-Omni强大的基座能力、海量多模态数据、跨语言…
|
||||
- 模型：`qwen3-livetranslate-flash-realtime`
|
||||
- [Qwen3.5-LiveTranslate-Flash-Realtime](groups/qwen3.5-livetranslate-flash-realtime.json) — Qwen3.5-LiveTranslate-Flash的实时版本，一款高精度、高响应、高鲁棒性的多语言实时音视频同传大模型。依托Qwen3.5-Omni强大的基座能力、海量多模态数据、跨语言跨模态对齐…
|
||||
- 模型：`qwen3.5-livetranslate-flash-realtime`
|
||||
|
||||
## 3D 生成 `3D-generation` — 1 个家族
|
||||
|
||||
- [Tripo](groups/tripo-models-market-place.json) — AI驱动的3D通用大模型Tripo，支持文本或图片输入，数秒内一键生成高质量3D模型。
|
||||
|
||||
@@ -60,7 +60,9 @@
|
||||
{"model":"glm-5.1","name":"GLM-5.1","family":"glm-4.5","familyName":"GLM","provider":"zhipu-ai","capabilities":["TG","Reasoning"],"features":["cache","function-calling","model-experience","structured-outputs"],"contextWindow":202745,"maxInputTokens":202745,"maxOutputTokens":131072,"inferenceMetadata":{"response_modality":["Text"],"request_modality":["Text"]},"qpmInfo":{"model-default-actual":{"count_limit":50,"count_limit_period":6,"usage_limit":100000,"usage_limit_field":"total_tokens","usage_limit_period":6},"model-default":{"count_limit":50,"count_limit_period":6,"usage_limit":100000,"usage_limit_field":"total_tokens","usage_limit_period":6}},"versionTag":"SNAPSHOT","docUrl":"https://www.alibabacloud.com/help/zh/document_detail/2974045.html","detailPath":"groups/glm-4.5.json"}
|
||||
{"model":"glm-5.2","name":"GLM-5.2","family":"glm-4.5","familyName":"GLM","provider":"zhipu-ai","capabilities":["TG","Reasoning"],"features":["cache","function-calling","model-experience","structured-outputs"],"contextWindow":1048576,"maxInputTokens":1048576,"maxOutputTokens":131072,"inferenceMetadata":{"response_modality":["Text"],"request_modality":["Text"]},"prices":[{"type":"input_token","unit":"每百万tokens","price":"8"},{"type":"output_token","unit":"每百万tokens","price":"28"},{"type":"input_token_cache","unit":"每百万tokens","price":"2"}],"qpmInfo":{"model-default-actual":{"count_limit":50,"count_limit_period":6,"usage_limit":2000000,"usage_limit_field":"total_tokens","usage_limit_period":60},"model-default":{"count_limit":50,"count_limit_period":6,"usage_limit":2000000,"usage_limit_field":"total_tokens","usage_limit_period":60}},"versionTag":"SNAPSHOT","docUrl":"https://help.aliyun.com/document_detail/2974045.html","detailPath":"groups/glm-4.5.json"}
|
||||
{"model":"glm-5.2-fast-preview","name":"GLM-5.2-Fast-Preview","family":"glm-fast","familyName":"GLM-5.2-Fast","provider":"zhipu-ai","capabilities":["TG"],"features":["cache","function-calling","prefix-completion","structured-outputs","web-search"],"contextWindow":1048576,"maxInputTokens":1048576,"maxOutputTokens":131072,"inferenceMetadata":{"response_modality":["Text"],"request_modality":["Text"]},"prices":[{"type":"input_token","unit":"每百万tokens","price":"16"},{"type":"output_token","unit":"每百万tokens","price":"56"},{"type":"input_token_cache","unit":"每百万tokens","price":"4"}],"qpmInfo":{"model-default-actual":{"count_limit":50,"count_limit_period":6,"usage_limit":100000,"usage_limit_field":"total_tokens","usage_limit_period":6},"model-default":{"count_limit":50,"count_limit_period":6,"usage_limit":100000,"usage_limit_field":"total_tokens","usage_limit_period":6}},"versionTag":"MAJOR","docUrl":"https://help.aliyun.com/document_detail/2974045.html","detailPath":"groups/glm-fast.json"}
|
||||
{"model":"gui-plus","name":"GUI-Plus","family":"gui-plus","familyName":"GUI-Plus","provider":"qwen-domain-model","capabilities":["VU"],"features":[],"contextWindow":256000,"maxInputTokens":254976,"maxOutputTokens":32768,"inferenceMetadata":{"response_modality":["Text"],"request_modality":["Text","Image"]},"prices":[{"type":"input_token","unit":"每百万tokens","price":"1.5"},{"type":"output_token","unit":"每百万tokens","price":"4.5"}],"qpmInfo":{"model-default-actual":{"count_limit":80,"count_limit_period":60,"usage_limit":540000,"usage_limit_field":"total_tokens","usage_limit_period":60},"model-default":{"count_limit":80,"count_limit_period":60,"usage_limit":540000,"usage_limit_field":"total_tokens","usage_limit_period":60}},"versionTag":"MAJOR","docUrl":"https://help.aliyun.com/document_detail/2997010.html","detailPath":"groups/gui-plus.json"}
|
||||
{"model":"gummy-chat-v1","name":"一句话识别及翻译V1.0","family":"gummy-chat-v1","familyName":"一句话识别及翻译V1.0","provider":"qwen","capabilities":["ASR"],"features":["model-experience"],"inferenceMetadata":{"response_modality":["Text"],"request_modality":["Audio"]},"prices":[{"type":"content_duration","unit":"每秒","price":"0.00015"}],"qpmInfo":{"model-default-actual":{"count_limit":10,"count_limit_period":1},"model-default":{"count_limit":10,"count_limit_period":1}},"versionTag":"MAJOR","docUrl":"https://help.aliyun.com/document_detail/2866122.html","detailPath":"groups/gummy-chat-v1.json"}
|
||||
{"model":"gummy-realtime-v1","name":"实时语音识别及翻译V1.0","family":"gummy-realtime-v1","familyName":"实时语音识别及翻译V1.0","provider":"qwen","capabilities":["Realtime-Audio-Translate"],"features":["model-experience"],"inferenceMetadata":{"response_modality":["Text"],"request_modality":["Audio"]},"prices":[{"type":"content_duration","unit":"每秒","price":"0.00015"}],"qpmInfo":{"model-default-actual":{"count_limit":10,"count_limit_period":1},"model-default":{"count_limit":10,"count_limit_period":1}},"versionTag":"MAJOR","docUrl":"https://help.aliyun.com/document_detail/2865393.html","detailPath":"groups/gummy-realtime-v1.json"}
|
||||
{"model":"happyhorse-1.0-i2v","name":"HappyHorse-1.0-I2V","family":"happyhorse-i2v","familyName":"HappyHorse-I2V","provider":"happyhorse","capabilities":["VG"],"features":["model-experience"],"inferenceMetadata":{"response_modality":["Video"],"request_modality":["Image","Text"]},"prices":[{"type":"video_ratio_720p","unit":"每秒","price":"0.9"},{"type":"video_ratio_1080p","unit":"每秒","price":"1.6"}],"qpmInfo":{"model-default-actual":{"count_limit":5,"count_limit_period":1},"model-default":{"count_limit":5,"count_limit_period":1}},"versionTag":"MAJOR","docUrl":"https://help.aliyun.com/document_detail/3029821.html","detailPath":"groups/happyhorse-i2v.json"}
|
||||
{"model":"happyhorse-1.1-i2v","name":"HappyHorse-1.1-I2V","family":"happyhorse-i2v","familyName":"HappyHorse-I2V","provider":"happyhorse","capabilities":["VG"],"features":["model-experience"],"inferenceMetadata":{"response_modality":["Video"],"request_modality":["Image","Text"]},"prices":[{"type":"video_ratio_480p","unit":"每秒","price":"0.45"},{"type":"video_ratio_720p","unit":"每秒","price":"0.9"},{"type":"video_ratio_1080p","unit":"每秒","price":"1.2"}],"qpmInfo":{"model-default-actual":{"count_limit":5,"count_limit_period":1},"model-default":{"count_limit":5,"count_limit_period":1}},"versionTag":"MAJOR","docUrl":"https://help.aliyun.com/document_detail/3029821.html","detailPath":"groups/happyhorse-i2v.json"}
|
||||
{"model":"happyhorse-1.0-r2v","name":"HappyHorse-1.0-R2V","family":"happyhorse-r2v","familyName":"HappyHorse-R2V","provider":"happyhorse","capabilities":["VG"],"features":["model-experience"],"inferenceMetadata":{"response_modality":["Video"],"request_modality":["Image","Text"]},"prices":[{"type":"video_ratio_720p","unit":"每秒","price":"0.9"},{"type":"video_ratio_1080p","unit":"每秒","price":"1.6"}],"qpmInfo":{"model-default-actual":{"count_limit":5,"count_limit_period":1},"model-default":{"count_limit":5,"count_limit_period":1}},"versionTag":"MAJOR","docUrl":"https://help.aliyun.com/document_detail/3030778.html","detailPath":"groups/happyhorse-r2v.json"}
|
||||
|
||||
-176
@@ -1,176 +0,0 @@
|
||||
# GetMemory - 获取长期记忆体
|
||||
|
||||
获取指定长期记忆体的描述信息。
|
||||
|
||||
## 接口说明
|
||||
|
||||
- 本接口具有幂等性。
|
||||
|
||||
**限流说明：** 请确保两次请求间隔至少 1 秒，否则可能触发系统限流。如遇限流，请稍后重试。
|
||||
|
||||
## 调试
|
||||
|
||||
[您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。](https://api.aliyun.com/api/bailian/2023-12-29/GetMemory)
|
||||
|
||||
[调试](https://api.aliyun.com/api/bailian/2023-12-29/GetMemory)
|
||||
|
||||
## 授权信息
|
||||
|
||||
下表是API对应的授权信息，可以在RAM权限策略语句的`Action`元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：
|
||||
|
||||
- 操作：是指具体的权限点。
|
||||
- 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
|
||||
- 资源类型：是指操作中支持授权的资源类型。具体说明如下：
|
||||
- 对于必选的资源类型，用前面加 \* 表示。
|
||||
- 对于不支持资源级授权的操作，用`全部资源`表示。
|
||||
- 条件关键字：是指云产品自身定义的条件关键字。
|
||||
- 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
|
||||
|
||||
操作
|
||||
|
||||
访问级别
|
||||
|
||||
资源类型
|
||||
|
||||
条件关键字
|
||||
|
||||
关联操作
|
||||
|
||||
sfm:GetMemory
|
||||
|
||||
get
|
||||
|
||||
\*全部资源
|
||||
|
||||
`*`
|
||||
|
||||
无
|
||||
|
||||
无
|
||||
|
||||
## 请求语法
|
||||
|
||||
```
|
||||
GET /{workspaceId}/memories/{memoryId} HTTP/1.1
|
||||
```
|
||||
|
||||
## 请求参数
|
||||
|
||||
名称
|
||||
|
||||
类型
|
||||
|
||||
必填
|
||||
|
||||
描述
|
||||
|
||||
示例值
|
||||
|
||||
workspaceId
|
||||
|
||||
string
|
||||
|
||||
是
|
||||
|
||||
长期记忆体所属的业务空间 ID。获取方式请参见[如何使用业务空间](https://help.aliyun.com/zh/model-studio/use-workspace)。
|
||||
|
||||
llm-3z7uw7fwz0vexxxx
|
||||
|
||||
memoryId
|
||||
|
||||
string
|
||||
|
||||
是
|
||||
|
||||
长期记忆体 ID，对应 [CreateMemory](https://help.aliyun.com/zh/model-studio/developer-reference/api-bailian-2023-12-29-creatememory) 接口返回的`memoryId`。
|
||||
|
||||
6bff4f317a14442fbc9f73d29dbxxxx
|
||||
|
||||
## 返回参数
|
||||
|
||||
名称
|
||||
|
||||
类型
|
||||
|
||||
描述
|
||||
|
||||
示例值
|
||||
|
||||
object
|
||||
|
||||
Schema of Response
|
||||
|
||||
description
|
||||
|
||||
string
|
||||
|
||||
长期记忆体的描述信息。
|
||||
|
||||
我的大模型应用$APP\_ID关于A用户的长期记忆体
|
||||
|
||||
memoryId
|
||||
|
||||
string
|
||||
|
||||
长期记忆体 ID。
|
||||
|
||||
6bff4f317a14442fbc9f73d29dbdxxxx
|
||||
|
||||
requestId
|
||||
|
||||
string
|
||||
|
||||
请求 ID。
|
||||
|
||||
6a71f2d9-f1c9-913b-818b-11402910xxxx
|
||||
|
||||
workspaceId
|
||||
|
||||
string
|
||||
|
||||
长期记忆体所属的业务空间 ID。
|
||||
|
||||
llm-3z7uw7fwz0vexxxx
|
||||
|
||||
## 示例
|
||||
|
||||
正常返回示例
|
||||
|
||||
`JSON`格式
|
||||
|
||||
```
|
||||
{
|
||||
"description": "我的大模型应用$APP_ID关于A用户的长期记忆体",
|
||||
"memoryId": "6bff4f317a14442fbc9f73d29dbdxxxx",
|
||||
"requestId": "6a71f2d9-f1c9-913b-818b-11402910xxxx",
|
||||
"workspaceId": "llm-3z7uw7fwz0vexxxx"
|
||||
}
|
||||
```
|
||||
|
||||
## 错误码
|
||||
|
||||
HTTP status code
|
||||
|
||||
错误码
|
||||
|
||||
错误信息
|
||||
|
||||
描述
|
||||
|
||||
404
|
||||
|
||||
Memory.MemoryIdNotFound
|
||||
|
||||
Memory Id not exist or is not authorized.
|
||||
|
||||
memoryId 未找到
|
||||
|
||||
500
|
||||
|
||||
Memory.InternalError
|
||||
|
||||
Memory service inner exception.
|
||||
|
||||
长期记忆服务内部异常。
|
||||
|
||||
访问[错误中心](< https://api.aliyun.com/document/bailian/2023-12-29/errorCode>)查看更多错误码。
|
||||
-1246
File diff suppressed because one or more lines are too long
@@ -1,58 +1,80 @@
|
||||
# 3d generation
|
||||
|
||||
百炼平台提供基于 Tripo 模型的 3D 模型生成能力，支持文生 3D、单图生 3D 和多图生 3D 三种输入模式。所有任务均采用异步调用流程（创建任务 → 轮询结果），适用于华北2（北京）地域，需配置对应地域的 API Key。详细实现细节请参考 [Tripo-3D模型生成](../../raw/model-api-reference/3d-generation/tripo-3d-generation-api-reference.md)。
|
||||
百炼平台提供基于 Tripo 模型的 3D 模型生成能力，支持文生 3D、单图生 3D 和多图生 3D 三种输入模式。所有任务均为异步执行，需通过 `task_id` 轮询获取结果，且**仅限华北2（北京）地域可用**。调用前需在百炼控制台开通 Tripo 服务并配置对应地域的 API Key。
|
||||
|
||||
## 支持的模型与功能
|
||||
## 支持的模型/功能
|
||||
|
||||
- **支持模型**：
|
||||
- **模型列表**：
|
||||
- `Tripo/Tripo-H3.1`：高精度生成，输出模型最高 200 万面，支持 `geometry_quality: "ultra"`；对应 Tripo 官方 API 版本 `v3.1-20260211`。
|
||||
- `Tripo/Tripo-P1.0`：专业级快速生成，输出模型最高 2 万面；对应 Tripo 官方 API 版本 `P1-20260311`。
|
||||
- **输入模式**（三者互斥）：
|
||||
- **生成模式**（三者互斥）：
|
||||
- 文生 3D：通过 `input.prompt` 输入文本描述；
|
||||
- 单图生 3D：通过 `input.image` 提供单张公网可访问图像 URL；
|
||||
- 多图生 3D：通过 `input.images` 提供长度为 4 的数组，按「前、左、后、右」顺序排列，缺失视角可用空对象 `{}` 占位。
|
||||
- 多图生 3D：通过 `input.images` 提供长度为 4 的数组，顺序固定为【前、左、后、右】，缺失视角填 `{}` 即可（实际有效图数需 ≥2）。
|
||||
- **输出类型**：
|
||||
- 默认返回 PBR 材质模型（GLB，含贴图），URL 字段为 `pbr_model_url`；
|
||||
- 无贴图模型需显式设置 `"texture": false, "pbr": false`，返回 `base_model_url`；
|
||||
- 所有成功响应均附带 `rendered_image_url`（预览图，WebP 格式）。
|
||||
- 默认返回 PBR 材质模型（`pbr_model_url`，GLB 格式）及预览图（`rendered_image_url`）；
|
||||
- 可显式禁用贴图与 PBR（需同时设 `"texture": false, "pbr": false`），此时返回无贴图基础模型（`base_model_url`）。
|
||||
|
||||
> **注意**：[Tripo-3D模型生成](../../raw/model-api-reference/3d-generation/tripo-3d-generation-api-reference.md) 明确要求仅支持华北2（北京）地域，且必须使用该地域的 API Key；跨地域调用将失败，此限制未在其他文档中被覆盖或修订。
|
||||
> **注意**：原始文档中 `Tripo/Tripo-H3.1` 的 `geometry_quality` 参数仅对该模型生效，但 [Tripo-3D模型生成](../../raw/model-api-reference/3d-generation/tripo-3d-generation-api-reference.md) 中未明确标注其对 `Tripo-P1.0` 不可用——实际调用将被忽略，开发者应避免在 `P1.0` 请求中传入该参数。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `model` | string | ✓ | 固定为 `Tripo/Tripo-H3.1` 或 `Tripo/Tripo-P1.0` |
|
||||
| `input.prompt` | string | 条件必填 | 文生 3D 时使用，≤1024 字符，支持中英文 |
|
||||
| `input.image` | string | 条件必填 | 单图生 3D 时使用，JPEG/PNG，宽高 ∈ [20, 6000] px，≤20 MB |
|
||||
| `input.images` | array[object] | 条件必填 | 多图生 3D 时使用，固定长度 4，每项含 `type`（jpeg/png）和 `file_token`（公网 URL） |
|
||||
| `parameters.texture_quality` | string | ✗ | 可选：`"standard"`（默认）、`"detailed"` |
|
||||
| `parameters.geometry_quality` | string | ✗ | 仅 `Tripo/Tripo-H3.1` 支持：`"standard"`（≤150 万面）、`"ultra"`（≤200 万面） |
|
||||
| `parameters.pbr` | boolean | ✗ | 默认 `true`；设为 `false` 时需同时设 `texture: false` 才生成无贴图模型 |
|
||||
| `parameters.texture` | boolean | ✗ | 默认 `true`；与 `pbr` 联动，共同控制贴图生成 |
|
||||
| `model` | string | ✅ | 固定为 `Tripo/Tripo-H3.1` 或 `Tripo/Tripo-P1.0` |
|
||||
| `input.prompt` | string | ⚠️（文生3D时必填） | 最长 1024 字符，支持中英文等多语言 |
|
||||
| `input.image` | string | ⚠️（单图生3D时必填） | 公网 HTTP/HTTPS URL；格式 JPEG/PNG；宽高 ∈ [20, 6000]px；≤20MB |
|
||||
| `input.images` | array[object] | ⚠️（多图生3D时必填） | 长度必须为 4；每项含 `type`（`jpeg`/`png`）和 `file_token`（URL）；空视角填 `{}` |
|
||||
| `parameters.texture_quality` | string | ❌（默认 `standard`） | 可选 `standard` / `detailed`；影响贴图分辨率 |
|
||||
| `parameters.geometry_quality` | string | ❌（仅 `H3.1` 有效） | 可选 `standard`（≤150 万面） / `ultra`（≤200 万面） |
|
||||
| `parameters.pbr` | boolean | ❌（默认 `true`） | 设为 `true` 时强制启用贴图；设为 `false` 时需同步设 `texture: false` 才得无贴图模型 |
|
||||
| `parameters.texture` | boolean | ❌（默认 `true`） | 与 `pbr` 联动；二者同为 `false` 时返回 `base_model_url` |
|
||||
|
||||
所有请求**必须包含**以下 Header：
|
||||
- `Content-Type: application/json`
|
||||
- `Authorization: Bearer $DASHSCOPE_API_KEY`
|
||||
- `X-DashScope-Async: enable`（缺此头将报错：“current user api does not support synchronous calls”）
|
||||
|
||||
详情参见 [Tripo-3D模型生成](../../raw/model-api-reference/3d-generation/tripo-3d-generation-api-reference.md) 中的请求头与请求体定义。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **开通与配置**
|
||||
在 [百炼控制台（北京地域）](https://bailian.console.aliyun.com/cn-beijing/?tab=model#/model-market/all) 搜索并开通 Tripo 模型；获取北京地域的 [API Key](https://bailian.console.aliyun.com/?tab=model#/api-key)，并配置至环境变量 `DASHSCOPE_API_KEY`。
|
||||
在 [百炼控制台（华北2）](https://bailian.console.aliyun.com/cn-beijing/?tab=model#/model-market/all) 搜索 “Tripo”，开通服务；按 [API Key 配置指南](https://help.aliyun.com/zh/model-studio/configure-api-key-through-environment-variables) 设置环境变量。
|
||||
|
||||
2. **发起[异步任务](../concepts/asynchronous-task.md)**
|
||||
向 `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation` 发送请求，**必须包含**以下请求头：
|
||||
- `Content-Type: application/json`
|
||||
- `Authorization: Bearer $DASHSCOPE_API_KEY`
|
||||
- `X-DashScope-Async: enable`（缺则报错）
|
||||
2. **创建任务（POST）**
|
||||
向 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation` 发送异步请求，获取 `task_id`（有效期 24 小时）。
|
||||
示例（文生3D）：
|
||||
```json
|
||||
{
|
||||
"model": "Tripo/Tripo-P1.0",
|
||||
"input": { "prompt": "一只可爱的猫" },
|
||||
"parameters": { "texture_quality": "standard" }
|
||||
}
|
||||
```
|
||||
|
||||
3. **轮询结果**
|
||||
使用返回的 `task_id`，以 `GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}` 查询状态。建议间隔 ≥15 秒轮询；`task_id` 有效期为 24 小时。更多操作详见 [Tripo-3D模型生成](../../raw/model-api-reference/3d-generation/tripo-3d-generation-api-reference.md) 中的“管理[异步任务](../concepts/asynchronous-task.md)”指引。
|
||||
3. **轮询结果（GET）**
|
||||
定期（建议 ≥15 秒间隔）调用 `GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}` 查询状态。
|
||||
状态流转：`PENDING` → `RUNNING` → `SUCCEEDED`/`FAILED`；`UNKNOWN` 表示 `task_id` 过期或无效。
|
||||
成功响应中 `output.results[0].pbr_model_url`（或 `base_model_url`）即为模型下载地址，**链接有效期仅 2 小时**，需及时保存。
|
||||
|
||||
完整流程与各模式示例详见 [Tripo-3D模型生成](../../raw/model-api-reference/3d-generation/tripo-3d-generation-api-reference.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域强约束**：仅支持华北2（北京）地域，URL、API Key、控制台入口均需匹配该地域；其他地域调用将失败。
|
||||
- **异步强制性**：不支持同步调用，`X-DashScope-Async: enable` 为必需头，否则返回 `current user api does not support synchronous calls` 错误。
|
||||
- **输入互斥性**：`prompt`、`image`、`images` 三者不可共存，同时传入将导致 `InvalidParameter` 错误。
|
||||
- **多图格式要求**：`input.images` 数组长度必须为 4，即使部分视角为空也需保留位置（用 `{}` 占位）；实际有效图片数应为 2–4 张。
|
||||
- **资源时效性**：`pbr_model_url`、`base_model_url`、`rendered_image_url` 均仅有效 2 小时，需及时下载；`task_id` 查询有效期为 24 小时，超时返回 `UNKNOWN` 状态。
|
||||
- **RPS 限制**：任务查询接口默认限流 20 QPS；高频轮询或需事件驱动，请配置 [异步任务回调](https://help.aliyun.com/zh/model-studio/async-task-api)。
|
||||
- **地域强约束**：仅支持华北2（北京）地域，其他地域 URL 无法调用，且 API Key 必须为该地域生成。
|
||||
- **异步强制性**：不支持同步调用；`X-DashScope-Async: enable` 为硬性要求。
|
||||
- **任务生命周期**：
|
||||
- `task_id` 有效期：24 小时（创建后起算）；
|
||||
- 模型下载 URL 有效期：2 小时（结果返回后起算）；
|
||||
- 查询接口 RPS 限制：默认 20，高频轮询建议配置 [异步回调](https://help.aliyun.com/zh/model-studio/async-task-api)。
|
||||
- **输入校验**：
|
||||
- `input.prompt`、`input.image`、`input.images` 三者严格互斥，同时存在将返回 `InvalidParameter` 错误；
|
||||
- `input.images` 数组长度必须为 4，否则报错；
|
||||
- 图像 URL 需公网可访问，且服务端能成功拉取（超时或 4xx/5xx 均失败）。
|
||||
- **资源消耗**：`H3.1` 模型生成耗时显著长于 `P1.0`，且 `ultra` 模式可能进一步延长处理时间，生产环境建议优先评估 `P1.0` 是否满足需求。
|
||||
|
||||
如遇错误，请依据响应中的 `code` 和 `message` 字段查阅 [错误码文档](https://help.aliyun.com/zh/model-studio/error-code)，具体字段说明亦见 [Tripo-3D模型生成](../../raw/model-api-reference/3d-generation/tripo-3d-generation-api-reference.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,48 +1,62 @@
|
||||
# application call
|
||||
|
||||
`application call` 是阿里云百炼平台提供的核心能力，用于通过 API 调用已发布的智能体（Agent）或工作流（Workflow）应用。开发者可通过 OpenAI 兼容的 Responses API 或原生 DashScope API 两种方式发起同步或异步请求，支持文本、图像、文件等多模态输入，并可选流式响应。调用前需明确应用类型、地域约束及凭证配置。
|
||||
`application call` 是指通过 API 调用阿里云百炼平台已发布的应用（包括新版智能体、旧版智能体、工作流等）的核心能力。开发者使用 APP ID（及必要时的 Workspace ID）和 API Key，向统一 endpoint 发起 HTTP 请求或调用 SDK，即可触发应用逻辑并获取结构化响应。该机制支持同步与异步两种模式，覆盖单轮/多轮对话、文本/图像/文件[多模态](../concepts/multi-modal.md)输入及[流式输出](../concepts/streaming-output.md)等典型场景。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **应用类型**：支持新版智能体（Agent 2.0）、旧版智能体及工作流三类应用，但不同 API 路径和参数要求存在差异。例如，[新版智能体应用 API 参考](../../raw/application-api-reference/application-call/application-dashscope-api-reference/new-agent-application-api-reference.md) 明确限定仅适用于新版智能体，而 [应用 DashScope API 参考](../../raw/application-api-reference/application-call/application-dashscope-api-reference/agent-and-workflow-application-api-reference.md) 则覆盖所有类型。
|
||||
- **多模态输入**：同步调用支持图像（`input_image`）和文件（`input_file`）输入，但文件输入**仅限智能体应用**，且需在应用内配置为“全文引用”或“切片检索”模式；图像输入则需选用通义千问 VL 系列模型并正确配置文件处理方式或模型节点入参 [同步调用 API 参考](../../raw/application-api-reference/application-call/openai-responses-api/synchronous-call-api-reference.md)。
|
||||
- **会话管理**：DashScope API 通过 `session_id` 实现多轮对话上下文维护（有效期 1 小时），而 Responses API 当前**不支持 `pre_response_id` 或 `conversation_id`**，必须在每次请求中显式传递完整消息历史 [同步调用 API 参考](../../raw/application-api-reference/application-call/openai-responses-api/synchronous-call-api-reference.md)。
|
||||
|
||||
> **注意**：文档 4 和文档 5 均描述了 `/api/v1/apps/{APP_ID}/completion` 接口，但文档 4 标题明确为“新版智能体应用 API”，文档 5 标题为“应用 DashScope API”且内容涵盖智能体与工作流。二者接口路径一致，但适用范围描述存在重叠与模糊。实际使用应以应用创建类型和控制台提示为准，建议优先参考 [应用 DashScope API 参考](../../raw/application-api-reference/application-call/application-dashscope-api-reference/agent-and-workflow-application-api-reference.md) 的通用说明。
|
||||
- **应用类型**：支持新版智能体（Agent 2.0）、旧版智能体、工作流三类应用；其中[新版智能体应用 API 参考](../../raw/application-api-reference/application-call/application-dashscope-api-reference/new-agent-application-api-reference.md)明确限定仅适用于华北2（北京）地域。
|
||||
- **[多模态](../concepts/multi-modal.md)能力**：
|
||||
- 图像输入：需选用通义千问 VL 系列模型，并在应用中配置为“自定义处理”（智能体）或模型节点入参变量设为 `imageList`（工作流）；
|
||||
- 文件输入：**仅智能体应用支持**，且需在应用内选择“全文引用”或“切片检索”[文件处理](../concepts/file-processing.md)方式；
|
||||
- **交互模式**：
|
||||
- 同步调用：适用于实时交互，即时返回结果，支持[流式输出](../concepts/streaming-output.md)（`stream=true`）；
|
||||
- 异步调用：适用于耗时任务（如复杂报告生成），通过 `background=true` 触发，返回任务 ID 后轮询状态；> **注意**：异步调用**不支持[流式输出](../concepts/streaming-output.md)**，此限制在[异步调用API参考](../../raw/application-api-reference/application-call/openai-responses-api/asynchronous-call-api-reference.md)中明确说明，与同步调用形成互补。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **`app_id`**（必选）：应用唯一标识，在 [应用管理](https://bailian.console.aliyun.com/#/app-center) 页面获取。若应用位于子业务空间或特定地域（如德国法兰克福、华北2北京、新加坡、日本东京），还需提供 `workspace_id` [获取APP ID和Workspace ID](../../raw/application-api-reference/application-call/obtain-the-app-id-and-workspace-id.md)。
|
||||
- **`input` / `prompt`**（必选）：
|
||||
- Responses API 使用 `input` 字段，支持字符串（单轮）或消息数组（多轮/多模态）；
|
||||
- DashScope API 使用 `prompt` 字段（单轮）或 `messages` 数组（多轮），结构更简洁。
|
||||
- **`stream`**（可选，Responses API）：布尔值，启用[流式输出](../concepts/streaming-output.md)。**注意**：异步调用（`background=true`）不支持[流式输出](../concepts/streaming-output.md) [异步调用API参考](../../raw/application-api-reference/application-call/openai-responses-api/asynchronous-call-api-reference.md)。
|
||||
- **`background`**（可选，Responses API）：布尔值，设为 `true` 即发起[异步任务](../concepts/asynchronous-task.md)，立即返回任务 ID。
|
||||
- **`biz_params`**（可选，Responses API 异步调用）：用于向工作流或智能体应用传递自定义参数（如城市名、索引值），需与应用内定义的参数名和类型严格匹配 [异步调用API参考](../../raw/application-api-reference/application-call/openai-responses-api/asynchronous-call-api-reference.md)。
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| `app_id` | string | 是 | 应用唯一标识，从[应用管理](https://bailian.console.aliyun.com/#/app-center)页面复制；若应用位于子业务空间或特定地域（如德国法兰克福），还需提供 `workspace_id` —— 获取方式详见[获取APP ID和Workspace ID](../../raw/application-api-reference/application-call/obtain-the-app-id-and-workspace-id.md)。 |
|
||||
| `input` | string 或 array | 是 | 核心输入内容：<br>- 字符串：用于单轮纯文本对话；<br>- 消息数组：用于多轮对话或含图片/文件的[多模态](../concepts/multi-modal.md)输入，格式需符合 OpenAI 兼容规范（`role`, `content` 等）。 |
|
||||
| `stream` | boolean | 否（默认 `false`） | 是否启用流式输出。仅同步调用有效；异步调用中设置 `true` 将被忽略。 |
|
||||
| `background` | boolean | 否（默认 `false`） | 是否启用异步模式。设为 `true` 时立即返回任务 ID，后续需调用 `retrieve` 查询结果。 |
|
||||
| `biz_params` | object | 否 | 传递应用内定义的**自定义参数**（如城市名、索引值等），参数名与类型须与应用配置严格一致；该参数仅在 OpenAI 兼容模式（Responses API）中生效。 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **同步调用（实时响应）**：
|
||||
- **Responses API**：Endpoint 为 `POST https://dashscope.aliyuncs.com/api/v2/apps/agent/{APP_ID}/compatible-mode/v1/responses`，推荐用于 OpenAI 生态迁移场景。
|
||||
- **DashScope API**：Endpoint 为 `POST https://dashscope.aliyuncs.com/api/v1/apps/{APP_ID}/completion`，SDK 调用更简洁，支持 `session_id` 维护会话。
|
||||
- **异步调用（长任务）**：
|
||||
- 仅 Responses API 支持，通过设置 `background=true` 发起，随后需轮询 `GET /responses/{task_id}` 获取状态与结果 [异步调用API参考](../../raw/application-api-reference/application-call/openai-responses-api/asynchronous-call-api-reference.md)。
|
||||
- **[流式输出](../concepts/streaming-output.md)**：
|
||||
- 仅 Responses API 同步调用支持，需设置 `stream=true` 并在应用端（工作流结束节点/流程输出节点）启用流式开关后重新发布 [同步调用 API 参考](../../raw/application-api-reference/application-call/openai-responses-api/synchronous-call-api-reference.md)。
|
||||
### 1. 基础调用路径
|
||||
- **DashScope 原生 API**（推荐用于高性能、全功能场景）：
|
||||
`POST https://dashscope.aliyuncs.com/api/v1/apps/{APP_ID}/completion`
|
||||
支持 Python/Java/Go 等 SDK 及 curl 直接调用，请求体为 `{"input": {"prompt": "..."}}` 格式。
|
||||
- **OpenAI 兼容 Responses API**（推荐用于快速迁移或复用 OpenAI 生态）：
|
||||
- 同步：`POST https://dashscope.aliyuncs.com/api/v2/apps/agent/{APP_ID}/compatible-mode/v1/responses`
|
||||
- 异步：同上 endpoint，但请求体中增加 `"background": true`。
|
||||
|
||||
### 2. 多轮对话实现
|
||||
- **DashScope API**：通过 `session_id` 维护上下文。首次请求不传，响应中返回 `session_id`；后续请求在参数中显式传入该 ID 即可延续会话（有效期 1 小时）。
|
||||
- **Responses API**：**不依赖 `session_id`**，而是要求在每次请求的 `input` 数组中**完整传递历史消息**（含 `user`/`assistant` 角色消息）。文档明确说明：“基于 `pre_response_id` 或 `conversation_id` 的上下文功能将在后续支持”。
|
||||
|
||||
### 3. 开发者工具链
|
||||
- **凭证配置**：API Key 建议通过环境变量 `DASHSCOPE_API_KEY` 设置，避免硬编码；
|
||||
- **调试入口**：控制台中进入 **应用卡片 → 发布 → API 调试**，可免代码验证参数与逻辑；
|
||||
- **SDK 选型**：
|
||||
- DashScope SDK：适配原生 API，功能最全；
|
||||
- OpenAI Python SDK（v1.0+）：适配 Responses API，兼容 `openai>=1.0.0` 接口。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域限制**：所有文档均强调“本文档仅适用于华北2（北京）地域”，但 [获取APP ID和Workspace ID](../../raw/application-api-reference/application-call/obtain-the-app-id-and-workspace-id.md) 明确指出 Workspace ID 在德国（法兰克福）、华北2（北京）、新加坡、日本（东京）地域下为必需。这意味着跨地域调用需严格匹配 Base URL 和 Workspace ID 配置。
|
||||
- **凭证获取**：APP ID 和 Workspace ID **只能通过控制台手动获取**，不支持 API 或 CLI 查询 [获取APP ID和Workspace ID](../../raw/application-api-reference/application-call/obtain-the-app-id-and-workspace-id.md)。
|
||||
- **权限要求**：查询所有业务空间 ID 需主账号或具备 `AliyunBailianFullAccess` 权限的 RAM 子账号，普通子账号仅能查看已加入的业务空间 [获取APP ID和Workspace ID](../../raw/application-api-reference/application-call/obtain-the-app-id-and-workspace-id.md)。
|
||||
- **API Key 安全**：所有示例均强调避免在生产代码中硬编码 `DASHSCOPE_API_KEY`，应优先使用环境变量配置。
|
||||
- **地域限制**：所有文档均强调当前 API 仅支持**华北2（北京）地域**，其他地域（如德国法兰克福、新加坡）虽需 `workspace_id`，但未明确其 API endpoint 是否可用，实际调用前需确认地域兼容性。
|
||||
- **凭证获取**：`APP ID` 和 `Workspace ID` **仅支持控制台手动获取**，不提供 API 或 CLI 查询接口，详见[获取APP ID和Workspace ID](../../raw/application-api-reference/application-call/obtain-the-app-id-and-workspace-id.md)。
|
||||
- **权限要求**：查询全部业务空间 ID 需主账号或具备 `AliyunBailianFullAccess` 权限的 RAM 子账号；普通子账号仅能查看已加入的业务空间。
|
||||
- > **注意**：文档 2 与文档 3 均声明“仅适用于华北2（北京）地域”，但文档 1 提到“德国（法兰克福）、华北2（北京）、新加坡、日本（东京）地域下的模型时，API 请求中才必须包含 `Workspace ID`”。此处存在隐含矛盾——文档 1 暗示这些地域的 API 是可用的，而文档 2/3 未覆盖；开发者应以控制台实际可用 endpoint 和错误提示为准，优先验证北京地域，再扩展至其他地域。
|
||||
- **异步任务管理**：异步调用后必须主动轮询 `retrieve` 接口获取结果，平台不提供 Webhook 回调；任务状态终态为 `completed`/`failed`/`cancelled`，需在代码中完整处理这三种情况。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [获取APP ID和Workspace ID](../../raw/application-api-reference/application-call/obtain-the-app-id-and-workspace-id.md)
|
||||
- [同步调用 API 参考](../../raw/application-api-reference/application-call/openai-responses-api/synchronous-call-api-reference.md)
|
||||
- [异步调用API参考](../../raw/application-api-reference/application-call/openai-responses-api/asynchronous-call-api-reference.md)
|
||||
- [新版智能体应用 API 参考](../../raw/application-api-reference/application-call/application-dashscope-api-reference/new-agent-application-api-reference.md)
|
||||
- [应用 DashScope API 参考](../../raw/application-api-reference/application-call/application-dashscope-api-reference/agent-and-workflow-application-api-reference.md)
|
||||
- [同步调用 API 参考](../../raw/application-api-reference/application-call/openai-responses-api/synchronous-call-api-reference.md)
|
||||
- [异步调用API参考](../../raw/application-api-reference/application-call/openai-responses-api/asynchronous-call-api-reference.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,56 +1,47 @@
|
||||
# application component api reference
|
||||
|
||||
本 API 参考文档面向开发者，系统性地描述了百炼平台 Application Component（应用组件）层提供的核心 OpenAPI 能力，覆盖数据连接（原应用数据）、知识库（Index）、切片（Chunk）、解析器配置及 Prompt 模板等关键功能模块。所有接口均基于 `bailian/2023-12-29` 版本，采用 ROA 签名机制，支持通过官方 SDK 快速集成。开发者需预先配置 RAM 权限与业务空间成员身份方可调用。
|
||||
本 API 参考文档面向开发者，系统性地描述了百炼平台 Application Component（应用组件）层提供的核心 OpenAPI 能力，覆盖数据连接（应用数据）、知识库（RAG）、切片管理、[Prompt 工程](../concepts/prompt-engineering.md)及辅助功能等模块。所有接口均基于 `bailian/2023-12-29` 版本，采用 ROA 签名机制，支持 SDK 封装调用与自签名接入。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
Application Component API 主要提供以下四类能力：
|
||||
|
||||
- **数据连接管理**：支持类目（Category）的增删查、文件（File）的上传（含 OSS 授权导入）、状态查询、标签更新及批量操作；支持连接器（Connector）的创建与配置。注意：[AddCategory - 新增类目](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-addcategory.md) 明确说明“每个业务空间最多创建500个类目”，且不支持通过 API 新增数据表。
|
||||
- **知识库（Index）全生命周期管理**：支持创建（`CreateIndex`）、提交构建任务（`SubmitIndexJob`）、追加文档（`SubmitIndexAddDocumentsJob`）、查询列表（`ListIndices`）、详情与文件列表（`ListIndexDocuments`/`ListIndexFileDetails`）、监控（`GetIndexMonitor`）、更新配置（`UpdateIndex`）及删除（`DeleteIndex`）。其中 `CreateIndex` 接口仅初始化作业，必须配合 `SubmitIndexJob` 才能完成知识库构建。
|
||||
- **文本切片（Chunk）操作**：支持为文档搜索类知识库新增（`AddChunk`）、修改（`UpdateChunk`）、删除（`DeleteChunk`）及查询（`ListChunks`）切片；数据查询/图片问答类知识库仅支持 `AddChunk`（需配合表格数据源），不支持 `UpdateChunk` 和 `DeleteChunk`。
|
||||
- **解析与模板能力**：支持获取/设置类目级解析器（`GetParseSettings`/`ChangeParseSetting`）、查询文件类型支持的解析器（`GetAvailableParserTypes`），以及创建 Prompt 模板（`CreatePromptTemplate`）。注意：[CreatePromptTemplate - 创建Prompt模板](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-prompt-engineering/api-bailian-2023-12-29-createprompttemplate.md) 明确声明“暂不支持文生图 Prompt 模板的创建”。
|
||||
|
||||
> **注意**：文档 4 中的版本变更记录显示 `CreateIndex` 在 2026-03-27 和 2026-03-30 两次变更入参，而文档 23 的 `CreateIndex` 接口说明中请求参数示例不完整（截断于 `Name` 字段），实际入参应以最新版 OpenAPI Explorer 或 SDK 文档为准。
|
||||
- **数据连接（原“应用数据”）**：管理结构化与非结构化数据源，包括类目（`AddCategory`, `ListCategory`, `DeleteCategory`）、文件（`AddFile`, `ListFile`, `DescribeFile`, `DeleteFile`）、表格（`AddTable`, `UpdateTableFromAuthorizedOss`）、连接器（`AddConnector`, `GetConnector`, `UpdateConnector`）及解析策略（`GetParseSettings`, `ChangeParseSetting`, `GetAvailableParserTypes`）。注意：[API概览](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-overview.md)明确指出，**不支持通过 API 新增或删除数据表**，该操作需通过控制台完成。
|
||||
- **知识库（RAG）**：支持知识库全生命周期管理，包括创建（`CreateIndex`）、提交构建任务（`SubmitIndexJob`）、追加文档（`SubmitIndexAddDocumentsJob`）、检索（`Retrieve`）、查询状态（`GetIndexJobStatus`）、列表与详情（`ListIndexDocuments`, `ListIndexFileDetails`）、监控（`GetIndexMonitor`）及删除（`DeleteIndex`）。其中，`CreateIndex` 接口仅初始化作业，必须配合 `SubmitIndexJob` 才能完成知识库构建。
|
||||
- **切片（Chunk）管理**：针对已构建的知识库，提供细粒度文本切片操作，包括查询（`ListChunks`）、新增（`AddChunk`）、修改（`UpdateChunk`）和删除（`DeleteChunk`）。> **注意**：`AddChunk` 和 `UpdateChunk` 的适用范围存在差异——前者支持 document/table/image 三类知识库，而后者**仅支持 document 类型**（见 [UpdateChunk - 修改切片](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-updatechunk.md) 文档说明）。
|
||||
- **辅助与工程能力**：包含 Prompt 模板（`CreatePromptTemplate`）、支付宝打赏（`GetAlipayUrl`, `GetAlipayTransferStatus`）及临时存储租约（`ApplyTempStorageLease`）等。其中 `CreatePromptTemplate` 明确不支持文生图模板创建。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **通用路径参数**：几乎所有接口均需 `WorkspaceId`（业务空间 ID），部分接口还需 `CategoryId`、`FileId`、`IndexId`、`PipelineId`（即 `IndexId`）等资源标识符。ID 均可通过控制台或对应 `List*` 接口获取。
|
||||
- **鉴权参数**：所有请求需携带标准阿里云签名（AccessKeyId + Signature），推荐使用 [阿里云百炼 SDK](https://api.aliyun.com/api-tools/sdk/bailian?version=2023-12-29) 自动处理。RAM 用户需具备 `AliyunBailianDataFullAccess` 或更细粒度策略（如 `sfm:AddFile`）。
|
||||
- **分页参数**：`List*` 类接口（如 `ListCategory`, `ListFile`, `ListIndices`）普遍支持 `MaxResults`/`NextToken`（ROA 风格）或 `PageNumber`/`PageSize`（RPC 风格）进行分页。
|
||||
- **文件解析参数**：`AddFile` 必须指定 `Parser`（如 `DOCMIND`, `AUTO_SELECT`）；`ApplyFileUploadLease` 的 `CategoryId` 可传 `default` 使用默认类目；`ChangeParseSetting` 需指定 `FileType`（如 `pdf`, `docx`）和 `CategoryId`。
|
||||
- **知识库检索参数**：`Retrieve` 接口核心参数为 `Query`（文本输入），无长度限制；`ListIndexDocuments` 支持按 `DocumentStatus`（如 `FINISH`, `PARSE_FAILED`）过滤。
|
||||
- **`WorkspaceId`（业务空间 ID）**：几乎所有接口的路径参数，用于标识资源所属的隔离域。获取方式详见 [如何使用业务空间](https://help.aliyun.com/zh/model-studio/use-workspace)。
|
||||
- **`CategoryId` / `FileId` / `IndexId` / `ConnectorId`**：各类资源的核心标识符，通常由上游接口（如 `AddCategory`, `AddFile`, `CreateIndex`, `AddConnector`）返回，后续操作需复用。
|
||||
- **`LeaseId` / `TempStorageLeaseId`**：文件上传必需的租约凭证，分别由 `ApplyFileUploadLease` 和 `ApplyTempStorageLease` 返回。
|
||||
- **`Parser`（解析器类型）**：在 `AddFile` 中指定，影响文档解析效果，可选值包括 `DOCMIND`, `DOCMIND_DIGITAL`, `DOCMIND_LLM_VERSION`, `DASH_QWEN_VL_PARSER` 等。
|
||||
- **`Query`（检索输入）**：`Retrieve` 接口的请求体参数，为原始文本 [prompt](../guides/prompt.md)，长度无硬性限制。
|
||||
- **`DocumentStatus`（文件状态过滤）**：在 `ListIndexDocuments` 和 `ListIndexFileDetails` 中用于按索引状态（如 `FINISH`, `PARSE_FAILED`）筛选结果。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **环境准备**：
|
||||
- 获取 AccessKey（建议使用最小权限的 RAM 用户，而非主账号）；
|
||||
- 加入目标业务空间；
|
||||
- 根据需求申请对应 RAM 权限（如 `sfm:AddFile`, `sfm:CreateIndex`）；
|
||||
- 选择接入点：例如华北2（北京）公网地址为 `bailian.cn-beijing.aliyuncs.com`（见 [服务接入点](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-endpoint.md)）。
|
||||
|
||||
2. **典型流程（以知识库为例）**：
|
||||
- 调用 `CreateIndex` 初始化知识库；
|
||||
- 调用 `ApplyFileUploadLease` → `AddFile`（或 `AddFilesFromAuthorizedOss`）上传文件至应用数据；
|
||||
- 调用 `SubmitIndexJob` 启动构建；
|
||||
- 调用 `GetIndexJobStatus` 轮询状态直至完成；
|
||||
1. **准备凭证**：使用 RAM 子账号（推荐）或阿里云主账号，配置最小权限策略（PoLP），并获取 AccessKey（见 [API概览](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-overview.md)）。RAM 权限策略需显式授予对应 Action（如 `sfm:AddFile`, `sfm:Retrieve`），详见 [授权信息](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-ram.md)。
|
||||
2. **选择接入点**：根据地域选择公网或 VPC 接入地址，例如华北2（北京）为 `bailian.cn-beijing.aliyuncs.com`（见 [服务接入点](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-endpoint.md)）。
|
||||
3. **调用流程示例（知识库）**：
|
||||
- 调用 `CreateIndex` 创建知识库（返回 `IndexId`）。
|
||||
- 调用 `AddFile` 上传文件（返回 `FileId`）。
|
||||
- 调用 `SubmitIndexJob` 提交构建任务（传入 `IndexId`）。
|
||||
- 调用 `GetIndexJobStatus` 轮询任务状态，直至完成。
|
||||
- 调用 `Retrieve` 进行检索。
|
||||
|
||||
3. **调试与开发**：
|
||||
- 优先使用 [OpenAPI Explorer](https://api.aliyun.com/api/bailian/2023-12-29/) 直接调试并生成 SDK 代码；
|
||||
- 生产环境强烈推荐使用官方 SDK（Java/Python/TypeScript 等），避免手动签名；
|
||||
- 文件上传需严格遵循租约流程（`ApplyFileUploadLease` → 上传至临时地址 → `AddFile`）。
|
||||
4. **SDK 优先**：强烈建议使用官方 SDK（如 Java/Python/TypeScript），其已封装签名逻辑并提供完整示例；自签名需严格遵循 ROA 规范，复杂度高且易出错。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **限流规则**：多数接口有明确 QPS 限制（如 `AddCategory`/`ListCategory` 为 5 次/秒，`AddFile`/`ApplyFileUploadLease` 为 10 次/秒），超限将返回错误，需实现重试退避逻辑。
|
||||
- **幂等性**：`List*`、`Describe*`、`Get*` 类只读接口及 `Delete*`、`Update*` 类部分接口（如 `DeleteCategory`, `DeleteFile`, `DeleteIndexDocument`）声明为幂等；`Add*`、`Create*`、`Submit*` 类接口通常不幂等，重复调用可能产生冗余资源。
|
||||
- **数据一致性**：删除操作分离明确——`DeleteFile` 删除应用数据中的文件，不影响已构建的知识库；`DeleteIndexDocument` 删除知识库中的索引内容，不影响原始应用数据文件。
|
||||
- **功能边界**：
|
||||
- 不支持通过 API 管理数据表（`AddTable` 存在但文档未详述其可用性，且 `ListCategory` 明确说明“暂不支持通过 API 查询数据表”）；
|
||||
- `DeleteIndex` 要求知识库未被应用关联，此解绑操作当前仅支持控制台；
|
||||
- `UpdateChunk` 和 `DeleteChunk` 仅适用于文档搜索类知识库，对数据查询/图片问答类无效。
|
||||
- **安全要求**：务必遵循最小权限原则配置 RAM 策略，并避免在客户端暴露 AccessKey。
|
||||
- **限流策略**：各接口有独立 QPS 限制（如 `AddCategory` 5次/秒，`AddFile` 10次/秒），超限将返回错误，需实现重试退避逻辑。
|
||||
- **幂等性**：多数查询类接口（如 `ListCategory`, `DescribeFile`）具有幂等性；写操作需自行判断（如 `CreateIndex` 不幂等，应先 `ListIndexDocuments` 再创建）。
|
||||
- **资源依赖与状态约束**：
|
||||
- 删除知识库（`DeleteIndex`）前，必须解除其与应用的关联（仅支持控制台操作）。
|
||||
- 删除知识库内文件（`DeleteIndexDocument`）仅支持状态为 `INSERT_ERROR` 或 `FINISH` 的文件。
|
||||
- 文件删除（`DeleteFile`）仅支持状态为 `PARSE_FAILED` 或 `PARSE_SUCCESS` 的文件。
|
||||
- **安全与权限**：RAM 用户必须加入目标业务空间并被授予对应 Action 权限（如 `AliyunBailianDataFullAccess`），否则调用失败。主账号虽默认拥有权限，但**强烈不建议直接使用主账号 AK**，应遵循最小权限原则。
|
||||
- **版本兼容性**：文档中多次提及变更（如 `CreateIndex` 入参变更、`DescribeFile` 返回结构变更），请以 [版本说明](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-changeset.md) 为准，及时更新集成代码。
|
||||
|
||||
## 来源文档
|
||||
|
||||
@@ -59,18 +50,18 @@ Application Component API 主要提供以下四类能力：
|
||||
- [授权信息](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-ram.md)
|
||||
- [版本说明](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-changeset.md)
|
||||
- [AddCategory - 新增类目](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-addcategory.md)
|
||||
- [ListCategory - 类目列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-listcategory.md)
|
||||
- [DeleteCategory - 删除类目](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-deletecategory.md)
|
||||
- [AddFile - 添加文件](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-addfile.md)
|
||||
- [ApplyFileUploadLease - 申请文件上传租约](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-applyfileuploadlease.md)
|
||||
- [ListFile - 文件列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-listfile.md)
|
||||
- [ListCategory - 类目列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-listcategory.md)
|
||||
- [AddFilesFromAuthorizedOss - 从已授权OSS Bucket中导入文件](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-addfilesfromauthorizedoss.md)
|
||||
- [AddFile - 添加文件](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-addfile.md)
|
||||
- [ListFile - 文件列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-listfile.md)
|
||||
- [DescribeFile - 查询文件状态](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-describefile.md)
|
||||
- [BatchUpdateFileTag - 批量更新文档标签](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-batchupdatefiletag.md)
|
||||
- [DeleteFile - 删除文件](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-deletefile.md)
|
||||
- [UpdateFileTag - 更新文件标签](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-updatefiletag.md)
|
||||
- [DeleteFiles - 批量删除文件](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-deletefiles.md)
|
||||
- [GetParseSettings - 获取类目解析设置](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-getparsesettings.md)
|
||||
- [GetAvailableParserTypes - 获取文件支持的解析器类型](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-getavailableparsertypes.md)
|
||||
- [ChangeParseSetting - 修改类目解析设置](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-changeparsesetting.md)
|
||||
- [AddTable - 添加表格](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-addtable.md)
|
||||
- [UpdateTableFromAuthorizedOss - 从已授权OSS Bucket中选择文件更新表格](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-updatetablefromauthorizedoss.md)
|
||||
- [AddConnector - 新增连接器](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-addconnector.md)
|
||||
@@ -79,38 +70,37 @@ Application Component API 主要提供以下四类能力：
|
||||
- [CreateIndex - 创建知识库](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-createindex.md)
|
||||
- [GetIndexJobStatus - 查询知识库创建任务状态](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-getindexjobstatus.md)
|
||||
- [SubmitIndexJob - 提交知识库创建任务](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-submitindexjob.md)
|
||||
- [UpdateFileTag - 更新文件标签](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-updatefiletag.md)
|
||||
- [SubmitIndexAddDocumentsJob - 提交知识库追加任务](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-submitindexadddocumentsjob.md)
|
||||
- [Retrieve - 检索知识库](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-retrieve.md)
|
||||
- [BatchUpdateFileTag - 批量更新文档标签](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-batchupdatefiletag.md)
|
||||
- [ListIndexDocuments - 查询知识库下的文件列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-listindexdocuments.md)
|
||||
- [ChangeParseSetting - 修改类目解析设置](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-changeparsesetting.md)
|
||||
- [DeleteIndexDocument - 删除知识库下的文件](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-deleteindexdocument.md)
|
||||
- [UpdateIndex - 更新知识库](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-updateindex.md)
|
||||
- [ListIndexFileDetails - 查询知识库下的文件详情](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-listindexfiledetails.md)
|
||||
- [DeleteFiles - 批量删除文件](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-data-connection-original-application-data/api-bailian-2023-12-29-deletefiles.md)
|
||||
- [DeleteIndexDocument - 删除知识库下的文件](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-deleteindexdocument.md)
|
||||
- [DeleteIndex - 删除知识库](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-deleteindex.md)
|
||||
- [ListChunks - 查询索引下的分片列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-listchunks.md)
|
||||
- [AddChunk - 新增切片](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-addchunk.md)
|
||||
- [UpdateChunk - 修改切片](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-updatechunk.md)
|
||||
- [ListIndices - 查询知识库列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-listindices.md)
|
||||
- [GetIndexMonitor - 获取知识库监控数据](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-getindexmonitor.md)
|
||||
- [DeleteChunk - 删除切片](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-deletechunk.md)
|
||||
- [GetIndexMonitor - 获取知识库监控数据](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-getindexmonitor.md)
|
||||
- [GetAlipayTransferStatus - 查询支付宝打赏状态](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-getalipaytransferstatus.md)
|
||||
- [GetAlipayUrl - 获取支付宝打赏URL](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-getalipayurl.md)
|
||||
- [ApplyTempStorageLease - 申请临时文件上传许可](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-applytempstoragelease.md)
|
||||
- [CreatePromptTemplate - 创建Prompt模板](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-prompt-engineering/api-bailian-2023-12-29-createprompttemplate.md)
|
||||
- [UpdatePromptTemplate - 更新Prompt模板](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-prompt-engineering/api-bailian-2023-12-29-updateprompttemplate.md)
|
||||
- [GetPromptTemplate - 获取Prompt模板](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-prompt-engineering/api-bailian-2023-12-29-getprompttemplate.md)
|
||||
- [UpdatePromptTemplate - 更新Prompt模板](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-prompt-engineering/api-bailian-2023-12-29-updateprompttemplate.md)
|
||||
- [DeletePromptTemplate - 删除Prompt模板](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-prompt-engineering/api-bailian-2023-12-29-deleteprompttemplate.md)
|
||||
- [ListPromptTemplates - 获取Prompt模板列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-prompt-engineering/api-bailian-2023-12-29-listprompttemplates.md)
|
||||
- [GetAlipayUrl - 获取支付宝打赏URL](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-getalipayurl.md)
|
||||
- [GetAlipayTransferStatus - 查询支付宝打赏状态](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-getalipaytransferstatus.md)
|
||||
- [ApplyTempStorageLease - 申请临时文件上传许可](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-applytempstoragelease.md)
|
||||
- [CreateMemory - 创建长期记忆体](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-creatememory.md)
|
||||
- [GetMemory - 获取长期记忆体](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-getmemory.md)
|
||||
- [UpdateIndex - 更新知识库](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-updateindex.md)
|
||||
- [ListIndices - 查询知识库列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-knowledge-base/api-bailian-2023-12-29-listindices.md)
|
||||
- [DeleteMemory - 删除长期记忆体](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-deletememory.md)
|
||||
- [UpdateMemory - 更新长期记忆体](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-updatememory.md)
|
||||
- [ListMemories - 获取长期记忆体列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-listmemories.md)
|
||||
- [CreateMemoryNode - 创建记忆片段](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-creatememorynode.md)
|
||||
- [GetMemoryNode - 获取记忆片段](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-getmemorynode.md)
|
||||
- [UpdateMemoryNode - 更新记忆片段](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-updatememorynode.md)
|
||||
- [CreateMemoryNode - 创建记忆片段](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-creatememorynode.md)
|
||||
- [DeleteMemoryNode - 删除记忆片段](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-deletememorynode.md)
|
||||
- [ListMemoryNodes - 获取记忆片段列表](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-listmemorynodes.md)
|
||||
- [UpdateMemory - 更新长期记忆体](../../raw/application-api-reference/application-component-api-reference/api-bailian-2023-12-29-dir/api-bailian-2023-12-29-dir-others/api-bailian-2023-12-29-dir-long-term-memory/api-bailian-2023-12-29-updatememory.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,53 +1,38 @@
|
||||
# file management api
|
||||
|
||||
文件管理 API 提供对百炼平台托管文件的全生命周期操作能力，包括上传、查询、列举和删除。该 API 与模型调用解耦，适用于预处理数据、构建知识库或管理训练/推理所需资源等场景。所有操作均需通过 `Authorization: Bearer <token>` 认证，并遵循统一的 RESTful 接口规范。
|
||||
文件管理 API 提供对百炼平台托管文件的全生命周期操作能力，包括上传、查询详情、列举已上传文件及删除文件。该 API 与模型调用解耦，不参与推理过程，仅用于文件资源的元数据与二进制内容管理。所有操作均需通过 `Authorization: Bearer <token>` 认证，并遵循平台统一的错误响应格式（详见 [文件管理 (raw/model-api-reference/file-management-api.md)](../../raw/model-api-reference/file-management-api.md)）。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
文件管理 API **不依赖特定大模型**，而是作为平台级基础设施服务，为所有支持文件输入的模型（如 Qwen 系列、Baichuan 系列、以及 [文件解析增强型模型](../../raw/model-api-reference/file-parsing-enhanced.md)）提供底层文件支撑。核心功能包括：
|
||||
- `POST /v1/files`：上传文件（支持 `multipart/form-data` 或 base64 编码）
|
||||
- `GET /v1/files/{file_id}`：根据 ID 查询单个文件元信息
|
||||
- `GET /v1/files`：分页列举当前项目下的全部文件（可选 `purpose` 过滤）
|
||||
- `DELETE /v1/files/{file_id}`：删除指定文件（不可恢复）
|
||||
|
||||
> **注意**：部分旧版文档中提及的 `/v1/files/upload_url` 预签名上传接口已废弃，当前仅支持直接上传；请以 [文件管理 (raw/model-api-reference/file-management-api.md)](../../raw/model-api-reference/file-management-api.md) 中的最新路径为准。
|
||||
- **当前仅支持通用文件管理功能**：上传（`POST /v1/files`）、查询单个文件（`GET /v1/files/{file_id}`）、列举文件列表（`GET /v1/files`）、删除文件（`DELETE /v1/files/{file_id}`）
|
||||
- 不绑定特定大模型，所有接入百炼平台的服务均可复用同一套文件 ID（`file_id`）在后续 API（如 `chat/completions` 中引用）
|
||||
- 文件类型限制见下文“限制和注意事项”，暂不支持直接调用模型进行文件解析或嵌入生成 —— 此类能力由 `embedding` 或 `document_parse` 等专用接口提供，而非本 API（参见 [文件管理 (raw/model-api-reference/file-management-api.md)](../../raw/model-api-reference/file-management-api.md)）
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 位置 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|------|
|
||||
| `file` | form-data body | file | 是 | 待上传的二进制文件（最大 512 MB） |
|
||||
| `purpose` | form-data body 或 query | string | 否 | 文件用途，取值 `fine-tune`、`assistants` 或 `batch`；未指定时默认为 `assistants` |
|
||||
| `file_id` | path | string | 是（除 POST 外） | 平台生成的唯一文件标识符，格式如 `file_abc123xyz` |
|
||||
| `limit` / `after` | query | integer / string | 否 | 分页参数，`limit` 默认 20，`after` 为上一页末尾的 `file_id` |
|
||||
| 参数 | 位置 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `file` | `multipart/form-data` body | 是 | 待上传的二进制文件，`Content-Type` 应与实际文件类型一致 |
|
||||
| `purpose` | form-data field | 否 | 取值为 `assistants`（默认）或 `vision`；影响后续在[多模态](../concepts/multi-modal.md)模型中的可用性，详见 [文件管理 (raw/model-api-reference/file-management-api.md)](../../raw/model-api-reference/file-management-api.md) |
|
||||
| `file_id` | URL path（查询/删除时） | 是 | 由上传成功响应返回的唯一标识符，全局唯一且不可修改 |
|
||||
|
||||
详细字段定义与响应结构见 [文件管理 (raw/model-api-reference/file-management-api.md)](../../raw/model-api-reference/file-management-api.md)。
|
||||
> **注意**：`purpose=vision` 仅对支持图像输入的模型生效；若上传图像后指定 `purpose=assistants`，则无法在 `qwen-vl` 等视觉模型中直接引用，需重新上传并设为 `vision`。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **上传文件**（示例）：
|
||||
```bash
|
||||
curl -X POST "https://dashscope.aliyuncs.com/api/v1/files" \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-F "file=@report.pdf" \
|
||||
-F "purpose=assistants"
|
||||
```
|
||||
|
||||
2. **获取文件列表**（带分页）：
|
||||
```bash
|
||||
curl "https://dashscope.aliyuncs.com/api/v1/files?limit=10&after=file_xyz789" \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
|
||||
```
|
||||
|
||||
3. 所有成功响应均为 JSON 格式，含 `id`、`filename`、`bytes`、`created_at`、`purpose` 等字段；错误响应遵循统一错误码体系（如 `401 Unauthorized`、`404 File not found`）。完整请求/响应示例参见 [文件管理 (raw/model-api-reference/file-management-api.md)](../../raw/model-api-reference/file-management-api.md)。
|
||||
1. **上传文件**：`POST https://dashscope.aliyuncs.com/api/v1/files`，携带 `file` 和可选 `purpose` 字段
|
||||
2. **获取文件信息**：`GET https://dashscope.aliyuncs.com/api/v1/files/{file_id}`
|
||||
3. **列举文件**：`GET https://dashscope.aliyuncs.com/api/v1/files?limit=20&offset=0`（支持分页）
|
||||
4. **删除文件**：`DELETE https://dashscope.aliyuncs.com/api/v1/files/{file_id}`
|
||||
所有响应均为 JSON 格式，含 `id`、`filename`、`bytes`、`created_at`、`purpose` 等字段。错误码遵循 RFC 7807 规范（如 `404 Not Found` 表示 `file_id` 不存在）。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- 单文件大小上限为 **512 MB**；超出将返回 `400 Bad Request`。
|
||||
- 每个项目（project）下最多存储 **10,000 个文件**；达到上限后需先清理再上传。
|
||||
- 已被模型引用的文件（如用于知识库或微调任务）**无法直接删除**，需先解除关联。
|
||||
- 文件上传后立即可用，但异步解析（如 PDF 文本提取）可能延迟数秒至数分钟，具体取决于文件类型与大小。
|
||||
- 删除操作不可逆，且不触发事件回调；建议业务侧自行记录关键操作日志。
|
||||
- 单文件大小上限：**512 MB**（超出将返回 `413 Payload Too Large`）
|
||||
- 支持格式：文本类（`.txt`, `.pdf`, `.docx`, `.xlsx`, `.csv`）、图像类（`.jpg`, `.png`, `.webp`），不支持 `.exe`, `.zip` 等可执行或压缩包格式
|
||||
- 文件保留策略：成功上传后默认**永久保留**，除非显式调用 DELETE；平台不自动清理闲置文件
|
||||
- `file_id` 一旦生成即固定，不可重用；重复上传同名文件会生成新 `file_id`
|
||||
- 删除操作**不可逆**，且删除后关联的模型调用（如已用于 `chat/completions` 的 `file_id`）将立即失效 —— 此行为与旧版文档中“软删除”描述矛盾，以当前接口实际行为为准（参见 [文件管理 (raw/model-api-reference/file-management-api.md)](../../raw/model-api-reference/file-management-api.md)）
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,51 +1,46 @@
|
||||
# frameworks
|
||||
|
||||
百炼平台提供多种主流 AI 开发框架的官方集成支持，帮助开发者快速构建 RAG 应用、知识库检索服务及大模型智能体/工作流应用。当前主要通过 LlamaIndex 和 Spring AI Alibaba 两大框架实现与百炼能力（如云端知识库、大模型服务、智能体引擎）的深度对接。所有集成均基于百炼 DashScope API 封装，需配合有效的 API Key 使用。
|
||||
阿里云百炼平台提供多种主流 AI 开发框架的集成支持，帮助开发者快速构建 RAG 应用、智能体/工作流应用及知识库检索服务。当前主要通过 LlamaIndex 和 Spring AI Alibaba 两大生态实现标准化接入，覆盖云端知识库托管、模型调用、检索增强与流式响应等核心能力。所有集成均依赖统一的 DashScope API 层，需配置有效的 `DASHSCOPE_API_KEY`。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **RAG 场景**：支持通过 LlamaIndex 构建端到端云端 RAG 应用，包括文档上传、自动切分、向量化、检索与生成全流程；也支持 Spring AI Alibaba 的 `DashScopeDocumentRetriever` 实现知识库检索增强问答 [通过Spring AI Alibaba检索阿里云百炼知识库](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-knowledge-base.md)。
|
||||
- **大模型应用调用**：支持通过 Spring AI Alibaba 的 `DashScopeAgent` 调用已发布的百炼智能体应用（Single Agent）和工作流应用（Workflow），支持非流式与流式响应 [使用Spring AI Alibaba集成阿里云百炼大模型应用](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-llm-application.md)。
|
||||
- **模型选择**：RAG 中生成阶段默认使用 `qwen-max`，但可显式指定其他千问系列模型（如 `qwen-plus`、`qwen-turbo`）；智能体调用时模型由应用内部配置决定，SDK 层不暴露模型切换参数。
|
||||
|
||||
> **注意**：文档 1 明确指出“不支持自定义文档切分方式或自定义嵌入模型”，而文档 2 和 3 均未提及嵌入模型控制能力，说明当前所有框架集成均依赖百炼托管的向量模型（如 `gte-rerank` 仅用于重排，非嵌入）。该限制在三份文档中一致，无需修正。
|
||||
- **RAG 场景**：支持基于 LlamaIndex 构建端到端[检索增强生成](../concepts/rag.md)应用，使用云端知识库（含自动文档切分与向量化），默认嵌入模型为官方向量模型（如 `gte-rerank`），不支持自定义切分逻辑或嵌入模型 [通过LlamaIndex API构建RAG应用](../../raw/application-api-reference/frameworks/llamaindex.md)。
|
||||
- **智能体与工作流**：Spring AI Alibaba 支持集成百炼平台创建的[智能体应用](https://help.aliyun.com/zh/model-studio/single-agent-application)和[工作流应用](https://help.aliyun.com/zh/model-studio/workflow-application/)，但**不支持直接集成知识库本身**（仅支持应用级调用） [使用Spring AI Alibaba集成阿里云百炼大模型应用](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-llm-application.md)。
|
||||
- **知识库直检**：Spring AI Alibaba 同时提供 `DashScopeDocumentRetriever` 组件，可直接对接已创建的百炼知识库（非应用），执行语义检索并注入上下文至 `qwen-max` 等模型生成回答 [通过Spring AI Alibaba检索阿里云百炼知识库](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-knowledge-base.md)。
|
||||
> **注意**：文档2称“仅支持集成智能体应用和工作流应用”，而文档3明确支持知识库直检；二者功能正交——前者调用封装好的业务逻辑应用，后者直接检索原始知识片段。开发者需根据场景选择：若需预置推理链路（如多步工具调用），选文档2；若需自主控制检索+生成流程，选文档3。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数名 | 来源框架 | 说明 | 示例值 |
|
||||
|--------|----------|------|--------|
|
||||
| `cloud_index_name` / `INDEX_NAME` | LlamaIndex / Spring AI Alibaba | 云端知识库名称（需提前在控制台创建） | `"my_first_index"` |
|
||||
| `model_name` | LlamaIndex（`Settings.llm`） | RAG 生成阶段调用的大模型 | `"qwen-max"` |
|
||||
| `AI_DASHSCOPE_API_KEY` / `DASHSCOPE_API_KEY` | Spring AI Alibaba（两种命名） | 百炼 API Key 环境变量名，文档 2 与文档 3 使用不同命名 | — |
|
||||
| `AI_DASHSCOPE_WORKSPACE_ID` / `WORKSPACE_ID` | Spring AI Alibaba（两种命名） | 子业务空间 ID 环境变量名，命名不一致需注意配置兼容性 | — |
|
||||
| `app-id` | Spring AI Alibaba（智能体） | 百炼大模型应用 ID，通过控制台获取 | `"app-xxx"` |
|
||||
|
||||
> **注意**：文档 2 使用 `AI_DASHSCOPE_API_KEY` 和 `AI_DASHSCOPE_WORKSPACE_ID`，而文档 3 使用 `DASHSCOPE_API_KEY` 和 `WORKSPACE_ID`。实际运行时需按所用 SDK 版本匹配环境变量名；Spring AI Alibaba 1.0.0.2 默认读取 `DASHSCOPE_API_KEY`（见文档 3 的 `pom.xml` 示例与 `application.yml` 配置），文档 2 的命名可能为旧版遗留或笔误，建议以文档 3 为准 [使用Spring AI Alibaba集成阿里云百炼大模型应用](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-llm-application.md)。
|
||||
| 参数名 | 说明 | 来源/示例 |
|
||||
|--------|------|-----------|
|
||||
| `APP_ID` | 智能体或工作流应用的唯一标识，必须配置于环境变量或 `application.yml` | [使用Spring AI Alibaba集成阿里云百炼大模型应用](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-llm-application.md) |
|
||||
| `DASHSCOPE_API_KEY` | 百炼平台 API 密钥，推荐设为环境变量；Spring AI Alibaba 示例中部分使用 `AI_DASHSCOPE_API_KEY`，存在命名不一致风险 | [通过Spring AI Alibaba检索阿里云百炼知识库](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-knowledge-base.md) |
|
||||
| `WORKSPACE_ID` / `AI_DASHSCOPE_WORKSPACE_ID` | 子业务空间 ID，用于跨空间访问知识库或应用；两文档使用不同环境变量名，实际调用时需按 SDK 版本对齐 | [使用Spring AI Alibaba集成阿里云百炼大模型应用](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-llm-application.md) 和 [通过Spring AI Alibaba检索阿里云百炼知识库](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-knowledge-base.md) |
|
||||
| `INDEX_NAME` | 知识库名称（字符串），用于 `DashScopeCloudIndex` 或 `DashScopeDocumentRetriever` 定位目标知识库 | [通过LlamaIndex API构建RAG应用](../../raw/application-api-reference/frameworks/llamaindex.md) 和 [通过Spring AI Alibaba检索阿里云百炼知识库](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-knowledge-base.md) |
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **LlamaIndex 集成**：
|
||||
1. 安装 `llama-index` 及 `llama-index-readers-dashscope`、`llama-index-indices-managed-dashscope` 等配套包；
|
||||
2. 使用 `DashScopeCloudIndex.from_documents()` 创建云端知识库；
|
||||
3. 通过 `index.as_query_engine()` 构建检索引擎，支持 `similarity_top_k`、`similarity_cutoff`、`node_postprocessors`（如 `DashScopeRerank`）等参数定制检索逻辑 [通过LlamaIndex API构建RAG应用](../../raw/application-api-reference/frameworks/llamaindex.md)。
|
||||
1. 使用 `DashScopeParse` 解析本地 `.txt`/`.docx`/`.pdf` 文件；
|
||||
2. 调用 `DashScopeCloudIndex.from_documents()` 上传并构建云端知识库；
|
||||
3. 通过 `index.as_query_engine()` 创建检索引擎，支持 `SimilarityPostprocessor` 和 `DashScopeRerank` 后处理；
|
||||
4. 设置 `Settings.llm = DashScope(model_name="qwen-max")` 指定生成模型。
|
||||
|
||||
- **Spring AI Alibaba 集成**：
|
||||
1. 添加 `spring-ai-alibaba-starter-dashscope` 依赖（版本 `1.0.0.2`）；
|
||||
2. 配置 `application.yml` 中 `spring.ai.dashscope.*` 相关属性；
|
||||
3. 对知识库场景，注入 `DashScopeDocumentRetriever` 并结合 `DocumentRetrievalAdvisor`；对智能体场景，使用 `DashScopeAgent` 调用 `call()` 或 `stream()` 方法。
|
||||
- **应用调用**：注入 `DashScopeAgent`，传入 `APP_ID` 调用预部署的智能体/工作流；支持非流式（`agent.call()`）与流式（`agent.stream()`）两种模式。
|
||||
- **知识库直检**：注入 `DashScopeApi`，构造 `DashScopeDocumentRetriever` 并绑定 `INDEX_NAME`，结合 `ChatClient` 与系统提示词模板实现 RAG 流程。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **知识库部署模式**：仅支持云端知识库，不支持本地知识库直连；文档切分与向量化完全由百炼托管，无法自定义解析器或嵌入模型 [通过LlamaIndex API构建RAG应用](../../raw/application-api-reference/frameworks/llamaindex.md)。
|
||||
- **文件格式限制**：LlamaIndex 方案仅支持 `.txt`、`.docx`、`.pdf` 等非结构化格式，不支持 Excel、PPT 或数据库直连。
|
||||
- **环境要求**：Spring AI Alibaba 要求 JDK 17+、Spring Boot 3.x；LlamaIndex 方案要求 Python 3.9+。
|
||||
- **业务空间隔离**：跨子业务空间访问知识库或应用时，必须正确配置 `workspace-id`（文档 2/3 均强调此点），否则请求将失败。
|
||||
- **计费说明**：框架本身免费，但所有模型调用（含 RAG 生成、智能体执行）均按百炼模型推理计费，详情见[计费项](https://help.aliyun.com/zh/model-studio/billing-for-model-studio#c1fabcbe9fklk)。
|
||||
- **知识库能力限制**：LlamaIndex 方案中，云端知识库强制使用默认文档切分策略与嵌入模型，不支持自定义切分规则或替换嵌入模型 [通过LlamaIndex API构建RAG应用](../../raw/application-api-reference/frameworks/llamaindex.md)。
|
||||
- **环境变量命名冲突**：Spring AI Alibaba 文档中 `API Key` 的环境变量名不统一（`DASHSCOPE_API_KEY` vs `AI_DASHSCOPE_API_KEY`），实际使用需以所引入 SDK 版本的 `spring-ai-alibaba-starter-dashscope` 文档为准，避免配置失效。
|
||||
- **依赖版本约束**：所有 Spring AI Alibaba 方案要求 JDK 17+ 和 Spring Boot 3.x；LlamaIndex 方案要求 Python 3.9+。
|
||||
- **计费说明**：百炼应用本身不收费，但模型调用（含 RAG 中的 `qwen-max` 推理、重排模型 `gte-rerank` 调用）按实际 token 量计费，详见[计费项](https://help.aliyun.com/zh/model-studio/billing-for-model-studio#c1fabcbe9fklk)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [通过LlamaIndex API构建RAG应用](../../raw/application-api-reference/frameworks/llamaindex.md)
|
||||
- [通过Spring AI Alibaba检索阿里云百炼知识库](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-knowledge-base.md)
|
||||
- [使用Spring AI Alibaba集成阿里云百炼大模型应用](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-llm-application.md)
|
||||
- [通过Spring AI Alibaba检索阿里云百炼知识库](../../raw/application-api-reference/frameworks/spring-ai-alibaba/spring-ai-alibaba-integrate-knowledge-base.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,84 +1,90 @@
|
||||
# image generation
|
||||
|
||||
百炼平台提供丰富的图像生成能力，涵盖文生图（T2I）、图生图（I2I）、图像编辑、局部重绘、背景生成、风格迁移等全栈式视觉生成任务。所有模型均通过统一的 HTTP API 接口调用，支持同步与异步两种模式，并已适配 DashScope SDK（Python/Java）。开发者需配置地域专属 API Key 与 Workspace ID 后即可集成。
|
||||
百炼平台提供丰富的图像生成与编辑能力，涵盖文生图、图生图、局部重绘、风格迁移、背景生成、AI试衣等20+类模型。所有服务均通过统一的HTTP API或DashScope SDK调用，支持同步/异步模式，并按实际成功生成图片计费。开发者需根据地域选择对应API Key与业务空间专属域名以保障稳定性与性能。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
百炼图像生成能力由多个专用模型构成，按任务类型可分为三类：
|
||||
百炼平台图像能力分为通用生成、专业编辑与创意工具三大类：
|
||||
|
||||
- **通用文生图**：`wan2.6-t2i`、`qwen-image-2.0-pro`、`z-image-turbo`、`kling/kling-v3-image-generation`、`vidu/vidu-image_reference2image` 等，支持自由提示词输入与多分辨率输出；
|
||||
- **图像编辑与增强**：`qwen-image-3.0-pro`（T2I+I2I一体化）、`wan2.7-image-pro`（4K文生图+2K编辑）、`wan2.5-i2i-preview`（单图/多图融合）、`wanx-image-edit`（去水印、扩图、超分等）；
|
||||
- **垂直场景工具**：`wanx-sketch-to-image-lite`（涂鸦作画）、`wanx-x-painting`（局部重绘）、`wanx-style-repaint-v1`（人像风格重绘）、`shoemodel-v1`（鞋靴试穿）、`image-out-painting`（画面扩展）、`image-erase-completion`（擦除补全）等 [原文标题](../../raw/model-api-reference/image-generation/wan-image-api-reference/wanx-image-edit-api-reference.md)。
|
||||
- **通用生成模型**：包括 `wan2.6-t2i`（万相V2文生图）、`qwen-image-3.0-pro`（千问3.0[多模态](../concepts/multi-modal.md)生成）、`z-image-turbo`（轻量级快速生图）和 `kling/kling-v3-omni-image-generation`（可灵分镜组图）。其中 `qwen-image-3.0-pro` 同时支持文生图（T2I）与图生图（I2I），且输出总像素需在512×512至2048×2048之间 [千问-图像生成与编辑3.0 API参考](../../raw/model-api-reference/image-generation/qwen-image-api-reference/qwen-image-generation-and-editing-api-reference.md)；`wan2.6-t2i` 支持自由选尺寸，总像素范围为[1280×1280, 1440×1440] [万相-文生图V2版API参考](../../raw/model-api-reference/image-generation/wan-image-api-reference/text-to-image-v2-api-reference.md)。
|
||||
|
||||
> **注意**：部分模型仅限华北2（北京）地域使用（如 `wanx-x-painting`、`shoemodel-v1`、`image-erase-completion`），且不支持付费续用，免费额度用尽后即不可调用，官方明确建议迁移到 [千问-图像编辑](https://help.aliyun.com/zh/model-studio/qwen-image-edit-guide) 或 [万相2.1图像编辑](https://help.aliyun.com/zh/model-studio/wanx-image-edit) [原文标题](../../raw/model-api-reference/image-generation/wan-image-api-reference/wanx-image-edit-api-reference.md)。
|
||||
- **专业编辑模型**：覆盖 `wan2.7-image-pro`（万相2.7图文混排与4K编辑）、`qwen-image-edit`（千问图像编辑，支持多图输入/输出及文字渲染增强）和 `vidu/vidu-image_reference2image`（Vidu参考生图，支持最多14张参考图）。
|
||||
|
||||
- **创意工具模型**：包括 `wanx-x-painting`（图像局部重绘）、`wanx-style-repaint-v1`（人像风格重绘）、`image-out-painting`（画面扩展）、`shoemodel-v1`（鞋靴模特）、`facechain`（人物写真训练与生成）及 `wordart`（创意文字变形与纹理生成）等垂直场景专用模型。部分模型如 `wanx-x-painting` 和 `shoemodel-v1` 当前仅提供免费体验，额度用尽后不可调用 [万相-图像局部重绘API参考](../../raw/model-api-reference/image-generation/wan-image-api-reference/vary-region-api-reference.md)。
|
||||
|
||||
> **注意**：文档中 `wanx-v1`（万相V1）明确标注“推荐使用全面升级的[文生图V2版模型](https://help.aliyun.com/zh/model-studio/text-to-image-v2-api-reference)”；而 `wan2.6-t2i` 文档指出其支持HTTP同步调用，但 `wan2.5` 及以下版本仅支持异步调用——二者能力存在代际差异，V2应为当前主力推荐版本。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 类型 | 说明 | 示例值 |
|
||||
|------|------|------|--------|
|
||||
| `model` | string | 必填，模型标识符，需与地域支持列表一致 | `"wan2.6-t2i"`, `"qwen-image-3.0-pro"` |
|
||||
| `size` | string / object | 图像分辨率，格式为 `"宽*高"` 或预设值（如 `"1K"`、`"2K"`、`"4K"`）；部分模型（如 `wan2.7-image-pro`）支持 `"1024*1024"`，`qwen-image-3.0-pro` 默认自动推荐 | `"1024*1024"`, `"2K"` |
|
||||
| `n` | integer | 生成图片数量，范围通常为 `1–9`（`wan2.6-t2i` 最高支持6张，`kling` 支持9张） | `2` |
|
||||
| `watermark` | boolean | 是否添加水印，默认 `true`；部分模型（如 `wan2.7-image-pro`）可设为 `false` | `false` |
|
||||
| `prompt_extend` | boolean | 是否启用智能提示词扩展（优化输入提示词并返回推理过程），增加响应延迟 | `true` |
|
||||
| `aspect_ratio` | string | 宽高比，仅 `kling` 等部分模型支持显式指定 | `"1:1"`, `"16:9"` |
|
||||
各模型共性参数如下，具体取值因模型而异：
|
||||
|
||||
> **注意**：`size` 参数行为存在不一致——`wan2.5-i2i-preview` 未指定时默认 `1280*1280` 并保持输入图宽高比，而 `qwen-image-3.0-pro` 未指定时由模型自动推荐分辨率 [原文标题](../../raw/model-api-reference/image-generation/qwen-image-api-reference/qwen-image-generation-and-editing-api-reference.md)。
|
||||
- `model`：必填字符串，指定模型ID（如 `"wan2.6-t2i"`、`"qwen-image-3.0-pro"`）。
|
||||
- `input.prompt` 或 `input.messages`：文本提示词，`qwen-image-3.0-pro` 等新模型要求使用 `messages` 格式（含 `role` 和 `content` 数组）。
|
||||
- `parameters.size`：图像分辨率，格式为 `"宽*高"`（如 `"1024*1024"`）或语义化值（如 `"1K"`、`"2K"`、`"4K"`）。`wan2.5-i2i-preview` 默认生成 `1280*1280` 图像并保持输入图宽高比 [万相-通用图像编辑2.5](../../raw/model-api-reference/image-generation/wan-image-api-reference/wan2-5-image-edit-api-reference.md)。
|
||||
- `parameters.n`：生成图片数量，范围通常为 `1–9`（`qwen-image-2.0-pro` 支持 `1–6` 张）。
|
||||
- `parameters.watermark`：布尔值，控制是否添加水印（默认 `true`）。
|
||||
- `X-DashScope-Async`：请求头必填项，异步调用必须设为 `"enable"`；同步调用（如 `wan2.6`）则不包含此头。
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 1. 基础前提
|
||||
- 获取对应地域的 [API Key](https://help.aliyun.com/zh/model-studio/get-api-key) 并配置至环境变量 `DASHSCOPE_API_KEY`；
|
||||
- 获取业务空间 ID（Workspace ID），用于构造请求 URL（如 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`）；
|
||||
- 所有模型均要求 `X-DashScope-Async: enable` 请求头（异步）或直接使用同步端点（仅 `wan2.6`、`qwen-image-3.0-pro`、`z-image-turbo` 等新协议模型支持）。
|
||||
### 域名与认证
|
||||
- **必须使用业务空间专属域名**：华北2（北京）为 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`，新加坡为 `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com`。旧域名 `dashscope.aliyuncs.com` 仍可用但不推荐 [千问-图像编辑API参考](../../raw/model-api-reference/image-generation/qwen-image-api-reference/qwen-image-edit-api.md)。
|
||||
- **API Key配置**：需提前获取并设为环境变量 `DASHSCOPE_API_KEY`，请求头中使用 `Authorization: Bearer $DASHSCOPE_API_KEY`。
|
||||
|
||||
### 2. 调用模式
|
||||
- **同步调用**（推荐多数场景）：适用于 `wan2.6-t2i`、`qwen-image-3.0-pro`、`z-image-turbo`，一次请求直接返回图像 Base64 或 URL；
|
||||
- **异步调用**（必需用于长耗时任务）：适用于 `wanx-v1`、`wanx-sketch-to-image-lite`、`wanx-x-painting` 等，需两步操作：
|
||||
1. `POST /api/v1/services/.../generation` 创建任务，获取 `task_id`；
|
||||
2. 轮询 `GET /api/v1/tasks/{task_id}` 查询状态，成功后返回图像 URL（有效期24小时）[原文标题](../../raw/model-api-reference/image-generation/wan-image-api-reference/text-to-image-api-reference.md)。
|
||||
### 调用模式
|
||||
- **同步调用**：适用于 `wan2.6-t2i`、`z-image-turbo` 等低延迟模型，单次请求返回结果。Endpoint为 `/api/v1/services/aigc/multimodal-generation/generation`。
|
||||
- **异步调用**：适用于耗时较长的模型（如局部重绘、虚拟模特），流程为两步：
|
||||
1. `POST /api/v1/services/.../generation` 创建任务，获取 `task_id`；
|
||||
2. 轮询 `GET /api/v1/tasks/{task_id}` 查询状态，成功后返回图片URL（有效期24小时）。
|
||||
|
||||
### 3. 输入结构
|
||||
- 文生图：`input.messages[].content[].text`（推荐）或 `input.prompt`（旧版兼容）；
|
||||
- 图生图/编辑：`input.messages[].content[]` 混合 `text` 与 `image` 对象（支持最多14张参考图，如 `vidu` 模型）；
|
||||
- 局部操作（重绘/擦除）：需传入 `base_image_url` + `mask_image_url`（白色区域为待处理区域）。
|
||||
### 示例命令
|
||||
```bash
|
||||
curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "wan2.6-t2i",
|
||||
"input": {"prompt": "一间花店，木质门，摆放花朵"},
|
||||
"parameters": {"size": "1024*1024", "n": 1}
|
||||
}'
|
||||
```
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域隔离**：华北2（北京）、新加坡、美国（弗吉尼亚）地域的 API Key 与请求地址**不可混用**，跨地域调用将鉴权失败；
|
||||
- **URL 可访问性**：所有输入图片 URL 必须支持公网访问，内网或私有 OSS 链接需生成临时公网 URL；
|
||||
- **免费额度**：多数模型提供 500 张/90 天免费额度（如 `wanx-v1`、`wanx-sketch-to-image-lite`），额度用尽后部分模型（如 `wanx-x-painting`、`shoemodel-v1`）直接停用，不支持付费；
|
||||
- **图像限制**：输入图分辨率通常需在 `[512, 4096]` 像素范围内，单图大小 ≤10 MB，格式支持 JPG/PNG/WEBP/BMP；
|
||||
- **错误处理**：常见报错 `"BadRequest.InputDownloadFailed"` 表示图片 URL 不可达，需检查链接有效性及权限 [原文标题](../../raw/model-api-reference/image-generation/image-faq.md)。
|
||||
- **地域隔离**：华北2（北京）、新加坡、美国（弗吉尼亚）地域的API Key与Endpoint不可混用，跨地域调用将鉴权失败。
|
||||
- **图片URL要求**：所有输入图片URL必须公网可访问、无中文路径、支持HTTP/HTTPS协议；OSS等云存储需配置公开读权限。
|
||||
- **免费额度与计费**：多数模型提供500张免费额度（90天有效），额度用尽后按单价计费（如 `wanx-v1` 为0.16元/张）。计费仅针对**成功生成的输出图片**，失败或输入图片不计入 [常见问题](../../raw/model-api-reference/image-generation/image-faq.md)。
|
||||
- **文件限制**：输入图像格式限于 JPG/PNG/WEBP/BMP/AVIF；分辨率通常要求 ≥512×512 且 ≤4096×4096；单图大小 ≤10MB。
|
||||
- **模型弃用风险**：`wanx-v1`、`wanx-x-painting`、`shoemodel-v1` 等模型明确标注“仅免费体验”或“推荐替代方案”，长期项目应优先选用 `qwen-image-3.0-pro` 或 `wan2.7-image-pro` 等持续维护的主力模型。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [常见问题](../../raw/model-api-reference/image-generation/image-faq.md)
|
||||
- [千问-图像编辑API参考](../../raw/model-api-reference/image-generation/qwen-image-api-reference/qwen-image-edit-api.md)
|
||||
- [千问-图像生成与编辑3.0 API参考](../../raw/model-api-reference/image-generation/qwen-image-api-reference/qwen-image-generation-and-editing-api-reference.md)
|
||||
- [千问-文生图API参考](../../raw/model-api-reference/image-generation/qwen-image-api-reference/qwen-image-api.md)
|
||||
- [千问-图像编辑API参考](../../raw/model-api-reference/image-generation/qwen-image-api-reference/qwen-image-edit-api.md)
|
||||
- [千问-图像翻译API参考](../../raw/model-api-reference/image-generation/qwen-image-api-reference/qwen-mt-image-api.md)
|
||||
- [Z-Image API参考](../../raw/model-api-reference/image-generation/z-image-generation-api-reference/z-image-api-reference.md)
|
||||
- [万相-文生图V2版API参考](../../raw/model-api-reference/image-generation/wan-image-api-reference/text-to-image-v2-api-reference.md)
|
||||
- [万相-图像生成与编辑2.7 API参考](../../raw/model-api-reference/image-generation/wan-image-api-reference/wan-image-generation-and-editing-api-reference.md)
|
||||
- [千问-文生图API参考](../../raw/model-api-reference/image-generation/qwen-image-api-reference/qwen-image-api.md)
|
||||
- [万相-文生图V1版API参考](../../raw/model-api-reference/image-generation/wan-image-api-reference/text-to-image-api-reference.md)
|
||||
- [万相-通用图像编辑2.5](../../raw/model-api-reference/image-generation/wan-image-api-reference/wan2-5-image-edit-api-reference.md)
|
||||
- [万相-图像生成与编辑2.7 API参考](../../raw/model-api-reference/image-generation/wan-image-api-reference/wan-image-generation-and-editing-api-reference.md)
|
||||
- [万相-图像生成与编辑2.6 API参考](../../raw/model-api-reference/image-generation/wan-image-api-reference/wan-image-generation-api-reference.md)
|
||||
- [万相-通用图像编辑2.5](../../raw/model-api-reference/image-generation/wan-image-api-reference/wan2-5-image-edit-api-reference.md)
|
||||
- [万相-通用图像编辑API参考](../../raw/model-api-reference/image-generation/wan-image-api-reference/wanx-image-edit-api-reference.md)
|
||||
- [万相-涂鸦作画API参考](../../raw/model-api-reference/image-generation/wan-image-api-reference/wanx-sketch-to-image-api-reference.md)
|
||||
- [万相-图像局部重绘API参考](../../raw/model-api-reference/image-generation/wan-image-api-reference/vary-region-api-reference.md)
|
||||
- [可灵-图像生成API参考](../../raw/model-api-reference/image-generation/kling-image-api-reference/kling-image-generation-api-reference.md)
|
||||
- [Z-Image API参考](../../raw/model-api-reference/image-generation/z-image-generation-api-reference/z-image-api-reference.md)
|
||||
- [Vidu-图像生成API参考](../../raw/model-api-reference/image-generation/vidu-image-models/vidu-image-generation-api-reference.md)
|
||||
- [人像风格重绘API参考](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/portrait-style-redraw-api-reference.md)
|
||||
- [鞋靴模特API参考](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/shoe-model-api.md)
|
||||
- [图像画面扩展API参考](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/image-scaling-api.md)
|
||||
- [虚拟模特API参考](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/virtual-model-api-details.md)
|
||||
- [鞋靴模特API参考](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/shoe-model-api.md)
|
||||
- [创意海报生成API参考](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/creative-poster-generation-api.md)
|
||||
- [人物实例分割API参考](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/image-instance-segmentation-api-reference.md)
|
||||
- [图像背景生成API参考](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/wanx-background-generation-api-reference.md)
|
||||
- [人物写真生成FaceChain](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/facechain-portrait-generation.md)
|
||||
- [AI试衣OutfitAnyone](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/outfitanyone.md)
|
||||
- [Vidu-图像生成API参考](../../raw/model-api-reference/image-generation/vidu-image-models/vidu-image-generation-api-reference.md)
|
||||
- [创意文字WordArt锦书](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/wordart-quick-start.md)
|
||||
- [人物实例分割API参考](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/image-instance-segmentation-api-reference.md)
|
||||
- [图像擦除补全API参考](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/image-erase-completion-api-reference.md)
|
||||
- [AI试衣OutfitAnyone](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/outfitanyone.md)
|
||||
- [人物写真生成FaceChain](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/facechain-portrait-generation.md)
|
||||
- [创意文字WordArt锦书](../../raw/model-api-reference/image-generation/image-creative-tools-api-reference/wordart-quick-start.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,52 +1,38 @@
|
||||
# knowledge
|
||||
|
||||
knowledge 是百炼平台提供的知识检索与问答能力，通过 HTTP REST 接口实现跨知识库的语义检索和基于知识的流式问答。该能力运行在 DashScope 应用网关体系下，与底层 OpenAPI（如 `CreateIndex`、`Retrieve` 等 RPC 接口）逻辑隔离，面向业务应用层提供开箱即用的 RAG 服务。详细设计与行为请参考 [知识检索与问答 (raw/application-api-reference/knowledge.md)](../../raw/application-api-reference/knowledge.md)。
|
||||
knowledge 是百炼平台提供的知识增强型 AI 服务模块，支持基于私有知识库的语义检索与多阶段智能问答。该能力通过 DashScope 应用网关提供 RESTful API，不依赖底层 OpenAPI RPC 接口（如 `CreateIndex`），适用于快速集成 RAG 场景。详细设计与行为请参考 [知识检索与问答 (raw/application-api-reference/knowledge.md)](../../raw/application-api-reference/knowledge.md)。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **知识检索**：支持跨多个知识库联合语义检索，返回按相关性排序的文本切片（chunk），适用于召回增强场景。
|
||||
- **知识问答**：支持端到端的智能问答流程，通过 SSE [流式输出](../concepts/streaming-output.md)，依次返回规划（planning）、工具调用（tool calling）、生成（generation）三个阶段结果，需配合已部署的知识应用 ID 使用。
|
||||
- 所有功能均基于 DashScope 应用网关提供，**不依赖用户自行托管模型或向量引擎**，底层模型由平台统一调度。具体能力边界详见 [知识检索与问答 (raw/application-api-reference/knowledge.md)](../../raw/application-api-reference/knowledge.md)。
|
||||
- **知识检索**：跨多个已发布知识库执行联合语义检索，返回按相关性排序的文本切片（chunk），适用于召回阶段。
|
||||
- **知识问答**：端到端问答流程，通过 SSE [流式输出](../concepts/streaming-output.md)，明确划分为「规划 → 工具调用 → 生成」三阶段，支持上下文感知与知识引用。
|
||||
> **注意**：知识问答不等同于通用大模型调用，其输入必须绑定已发布的应用 ID（`app_id`），且仅作用于该应用关联的知识库；该约束在 [知识检索与问答 (raw/application-api-reference/knowledge.md)](../../raw/application-api-reference/knowledge.md) 中明确，但部分旧版 SDK 示例未体现，实际调用时需严格校验。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| 参数 | 说明 | 必填 | 示例 |
|
||||
|------|------|------|------|
|
||||
| `workspaceId` | string | 是 | 业务空间 ID，用于构造 Base URL（`https://{workspaceId}.cn-beijing.maas.aliyuncs.com`），非 AccessKey 或 Region ID |
|
||||
| `Authorization` | header | 是 | `Bearer <API-Key>`，API Key 需在控制台 [API Key 页面](https://rag.console.aliyun.com/settings/apikey) 获取 |
|
||||
| `app_id` | body（仅 `/chat`） | 是 | 已发布的知识应用 ID，对应控制台中“知识应用”模块下的唯一标识 |
|
||||
| `query` | body | 是 | 检索或问答的原始用户输入文本 |
|
||||
|
||||
> **注意**：`workspaceId` 与百炼控制台中的“业务空间”ID 完全一致，**不可替换为 Project ID 或 UID**；部分旧文档误将 `workspaceId` 描述为“区域+实例ID”，该说法已过时，请以 [知识检索与问答 (raw/application-api-reference/knowledge.md)](../../raw/application-api-reference/knowledge.md) 中定义为准。
|
||||
| `Authorization` | Bearer 鉴权头，值为 `Bearer <API-Key>` | 是 | `Bearer ak-xxx` |
|
||||
| `workspaceId` | 业务空间 ID，用于构造 Base URL（`https://{workspaceId}.cn-beijing.maas.aliyuncs.com`） | 是 | `ws-abc123` |
|
||||
| `app_id` | 知识问答必需，对应控制台中已发布的知识应用 ID | 仅 `/api/v2/apps/knowledge/chat` 需要 | `app-xyz789` |
|
||||
| `query` | 检索或问答的原始用户输入文本 | 是 | `"阿里云百炼支持哪些知识格式？"` |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **构造请求地址**：
|
||||
- 知识检索：`POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search`
|
||||
- 知识问答：`POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/knowledge/chat`
|
||||
|
||||
2. **设置请求头**：
|
||||
```http
|
||||
Authorization: Bearer <your-api-key>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
3. **发送 JSON Body（示例）**：
|
||||
```json
|
||||
{
|
||||
"query": "百炼平台如何配置知识库权限？",
|
||||
"top_k": 5
|
||||
}
|
||||
```
|
||||
> 注意：`top_k` 仅对 `/search` 有效；`/chat` 接口不接受 `top_k`，其召回策略由绑定的知识应用配置决定。
|
||||
1. 在控制台获取 **API Key**（见 [API Key 页面](https://rag.console.aliyun.com/settings/apikey)）和 **workspaceId**（见 [业务空间管理](https://bailian.console.aliyun.com/cn-beijing?tab=globalset#/efm/business_management)）；
|
||||
2. 构造请求 URL：
|
||||
- 检索：`POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search`
|
||||
- 问答：`POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/knowledge/chat`
|
||||
3. 设置 `Authorization` 请求头；
|
||||
4. 发送 JSON body（检索含 `query`、`top_k`；问答含 `app_id`、`query`、`stream` 等）。
|
||||
完整字段定义与示例见 [知识检索与问答 (raw/application-api-reference/knowledge.md)](../../raw/application-api-reference/knowledge.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **限流策略**：默认按用户维度限流 25 QPS，超限返回 `429 Too Many Requests`，需客户端实现退避重试。
|
||||
- **鉴权隔离**：API Key 与 workspaceId 必须匹配同一业务空间，跨空间调用将返回 `403 Forbidden`。
|
||||
- **知识问答依赖部署状态**：`/chat` 接口要求 `app_id` 对应的知识应用已**发布成功且状态为“运行中”**，草稿或停用状态将返回 `404 Not Found`。
|
||||
- **无批量接口**：当前不支持单次请求多 query 批处理，需逐条调用。
|
||||
- **SSE 兼容性**：`/chat` 返回流式响应，需客户端正确处理 `text/event-stream` MIME 类型及 `data:` 前缀格式。
|
||||
- **限流策略**：默认按用户维度限流 25 QPS，超限返回 `429 Too Many Requests`，需客户端实现退避重试；
|
||||
- **知识库状态要求**：仅已「发布」的知识库参与检索/问答，草稿或下线状态不可见；
|
||||
- **问答流式响应结构固定**：SSE event 类型依次为 `plan` → `tool_call` → `answer`，解析时须按序处理，不可假设单次响应即完成；
|
||||
- **Base URL 区域固定**：当前仅支持 `cn-beijing` 地域，`{workspaceId}` 不可替换为其他地域标识。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,54 +1,70 @@
|
||||
# long term memory new
|
||||
|
||||
[长期记忆](../concepts/long-term-memory.md)（新）是百炼平台提供的结构化用户状态持久化能力，支持自动从对话中提取关键信息、构建用户画像，并提供语义搜索、增删改查等完整生命周期管理。该能力基于专用记忆模型实现，无需开发者自行训练或部署 Embedding 模型。所有 API 均通过 `https://dashscope.aliyuncs.com/api/v2/apps/memory/` 统一入口访问，认证方式为 Bearer [Token](../concepts/token.md) [原文标题](../../raw/application-api-reference/long-term-memory-new/long-term-memory-api-reference.md)。
|
||||
[长期记忆](../concepts/long-term-memory.md)（新）是百炼平台提供的结构化用户记忆管理能力，支持自动从对话中提取关键信息生成记忆片段，并提供语义搜索、增删改查等完整生命周期管理。该能力基于专用模型实现意图理解与信息抽取，适用于构建具备上下文感知能力的智能体应用。详细接口定义和行为规范请参见 [长期记忆（新）API 参考](../../raw/application-api-reference/long-term-memory-new/long-term-memory-api-reference.md)。
|
||||
|
||||
## 支持的模型与功能
|
||||
## 支持的模型/功能
|
||||
|
||||
- **底层模型**：由百炼平台统一托管的记忆专用模型（非公开型号），不开放模型选择，所有接口均自动路由至最优模型。
|
||||
- **核心功能**：
|
||||
- `AddMemory`：自动解析对话（最多 50 条消息）或接收自定义文本，生成结构化记忆片段，并可关联画像模板；
|
||||
- `SearchMemory`：基于语义相似度检索，支持 `top_k`、`min_score`、`enable_rerank` 等精细控制；
|
||||
- `ListMemory` / `DeleteMemory` / `UpdateMemory`：标准 CRUD 操作；
|
||||
- `ProfileSchema` 系列接口：管理用户画像模板（创建、更新、删除、获取），用于约束记忆提取的字段结构；
|
||||
- `GetUserProfile`：按模板拉取聚合后的用户画像快照。
|
||||
|
||||
> **注意**：文档中提及的 `agentscope-runtime>=1.1.5` SDK 封装了 `AddMemory`、`SearchMemory`、`ListMemory`、`DeleteMemory` 四个工具，但明确说明 `UpdateMemory` “Python SDK 暂未提供此接口的封装” [原文标题](../../raw/application-api-reference/long-term-memory-new/long-term-memory-api-reference.md)，需直接调用 REST API 实现。
|
||||
- **核心能力**：自动从 `messages` 对话流中提取结构化记忆（如提醒、偏好、事件），或接受 `custom_content` 直接注入文本；
|
||||
- **画像联动**：支持通过 `profile_schema_id` 关联画像模板，将记忆片段映射至用户画像字段；
|
||||
- **[多模态](../concepts/multi-modal.md)适配**：`messages.content` 支持 string 或 array 类型（如含 image_url 的[多模态](../concepts/multi-modal.md)消息），但当前仅对文本内容进行语义解析；
|
||||
- **检索增强**：`SearchMemory` 支持 `enable_rerank`、`enable_judge`、`enable_rewrite` 等高级搜索开关，需在请求中显式启用；
|
||||
- 所有功能均依赖百炼平台统一认证体系，无需额外模型部署。具体能力边界详见 [长期记忆（新）API 参考](../../raw/application-api-reference/long-term-memory-new/long-term-memory-api-reference.md)。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| `user_id` | string | 是 | 记忆归属标识，最大 64 字符；所有接口均需传入，用于隔离不同用户数据 |
|
||||
| `memory_library_id` | string | 否 | 记忆库 ID（32 字符），不传则使用默认库；可在[控制台记忆库列表页](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/memory/list)获取 [原文标题](../../raw/application-api-reference/long-term-memory-new/long-term-memory-api-reference.md) |
|
||||
| `messages` 或 `custom_content` | array / string | 互斥必填 | `AddMemory` 中二选一：`messages` 为 role/content 对话数组（一问一答计 2 条），`custom_content` 为纯文本（≤512 字符） |
|
||||
| `top_k` | integer | 否（SearchMemory） | 召回数量，默认 10，范围 1–100 |
|
||||
| `min_score` | double | 否（SearchMemory） | 相似度阈值，默认 0.3，范围 [0,1] |
|
||||
| `profile_schema` | string | 否（AddMemory） | 画像模板 ID，影响记忆提取字段；在记忆库详情页获取 [原文标题](../../raw/application-api-reference/long-term-memory-new/long-term-memory-api-reference.md) |
|
||||
| `user_id` | string | 是 | 记忆归属实体 ID（≤64 字符），用于隔离不同用户数据 |
|
||||
| `messages` / `custom_content` | array / string | 互斥必填 | `messages` 最多 50 条（一问一答计为 2 条）；`custom_content` ≤512 字符 |
|
||||
| `memory_library_id` | string | 否 | 显式指定记忆库 ID（≤32 字符），不传则使用默认库；[获取方式见控制台](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/memory/list) |
|
||||
| `profile_schema_id` | string | 否 | 画像模板 ID，用于约束记忆片段结构化输出格式 |
|
||||
| `top_k`（SearchMemory） | integer | 否 | 检索召回数（1–100，默认 10） |
|
||||
| `min_score`（SearchMemory） | double | 否 | 相似度阈值 [0,1]（默认 0.3） |
|
||||
|
||||
> **注意**：`project_id` 参数在文档中描述为“记忆片段规则 ID”，但实际调用中若未传入，系统会自动选择默认规则；该行为与 [长期记忆（新）API 参考](../../raw/application-api-reference/long-term-memory-new/long-term-memory-api-reference.md) 中“说明”字段一致，无需手动指定。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **认证**：所有请求 Header 需携带 `Authorization: Bearer $DASHSCOPE_API_KEY`，API Key 获取方式见[官方指南](https://help.aliyun.com/zh/model-studio/get-api-key)。
|
||||
2. **SDK 调用（推荐）**：
|
||||
- 安装：`pip install agentscope-runtime>=1.1.5`
|
||||
- 示例（AddMemory）：
|
||||
```python
|
||||
from agentscope_runtime.tools.modelstudio_memory import AddMemory, Message, AddMemoryInput
|
||||
result = await AddMemory().arun(AddMemoryInput(
|
||||
user_id="user_001",
|
||||
messages=[Message(role="user", content="每天9点提醒我喝水")]
|
||||
))
|
||||
```
|
||||
3. **REST 直连（如 UpdateMemory）**：
|
||||
- PATCH `/api/v2/apps/memory/memory_nodes/{memory_node_id}`
|
||||
- Body 包含 `user_id`、`custom_content` 等必需字段。
|
||||
### 基础调用
|
||||
- **Base URL**：`https://dashscope.aliyuncs.com/api/v2/apps/memory/`
|
||||
- **认证**：Header 中携带 `Authorization: Bearer $DASHSCOPE_API_KEY`
|
||||
- **Content-Type**：`application/json`
|
||||
|
||||
### SDK 快速接入
|
||||
- Python 推荐使用 `agentscope-runtime>=1.1.5`：
|
||||
- `AddMemory`, `SearchMemory`, `ListMemory` 已封装为异步工具类；
|
||||
- `DeleteMemory` 和 `UpdateMemory` 也提供封装，但 `UpdateMemory` 的 Python 示例中明确提示“SDK 暂未提供封装”，需用 `requests` 直接调用 —— 此处存在文档内不一致，**以 [长期记忆（新）API 参考](../../raw/application-api-reference/long-term-memory-new/long-term-memory-api-reference.md) 中 Python 示例为准**。
|
||||
|
||||
### 典型流程示例
|
||||
```python
|
||||
# 添加记忆（自动抽取）
|
||||
await AddMemory().arun(AddMemoryInput(
|
||||
user_id="user_001",
|
||||
messages=[Message(role="user", content="明天9点开会"), Message(role="assistant", content="已记录")],
|
||||
meta_data={"source": "chat"}
|
||||
))
|
||||
|
||||
# 搜索相关记忆
|
||||
await SearchMemory().arun(SearchMemoryInput(
|
||||
user_id="user_001",
|
||||
messages=[Message(role="user", content="我之前有什么待办？")],
|
||||
top_k=5,
|
||||
min_score=0.5
|
||||
))
|
||||
```
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **限流**：全接口总计 ≤3000 QPM（阿里云账号级）；其中 `AddMemory` ≤120 QPM，`SearchMemory` ≤300 QPM。
|
||||
- **数据时效**：当前生成的记忆片段与用户画像**无自动失效机制**，需业务层自行管理生命周期 [原文标题](../../raw/application-api-reference/long-term-memory-new/long-term-memory-api-reference.md)。
|
||||
- **内容长度**：`custom_content` 最大 512 字符；`messages` 最多 50 条记录。
|
||||
- **字段覆盖**：`UpdateMemory` 的 `meta_data` 为**增量更新**（非全量替换），仅合并新键值对。
|
||||
- **时间戳**：`UpdateMemory` 的 `timestamp` 字段为秒级 Unix 时间戳（可选），若不传则使用请求时刻。
|
||||
- **限流策略**（阿里云账号级别）：
|
||||
- 全部接口总计 ≤3000 QPM；
|
||||
- `AddMemory` 单独限流 ≤120 QPM；
|
||||
- `SearchMemory` 单独限流 ≤300 QPM；
|
||||
- **数据持久性**：记忆片段与用户画像无自动过期机制，需业务侧自行管理生命周期；
|
||||
- **内容长度**：`custom_content` 和单条 `messages.content` 均受 512 字符限制，超长内容将被截断；
|
||||
- **时间戳精度**：`UpdateMemory` 的 `timestamp` 为秒级 Unix 时间戳，毫秒级输入会被向下取整；
|
||||
- **错误处理**：所有接口返回 `request_id`，用于问题排查；失败时 HTTP 状态码非 2xx，响应体含 `code` 与 `message` 字段。
|
||||
|
||||
> **注意**：文档中 `DeleteMemory` 的 cURL 示例路径含 `{memory_node_id}` 占位符，但未说明需替换为真实 ID；实际调用时必须替换，否则返回 404。该细节在 [长期记忆（新）API 参考](../../raw/application-api-reference/long-term-memory-new/long-term-memory-api-reference.md) 的“路径参数”小节有明确定义，开发者需严格遵循。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,67 +1,67 @@
|
||||
# [managed agents](../guides/managed-agents.md) api
|
||||
|
||||
Managed Agents API 是百炼平台提供的智能体托管运行时服务，由平台统一管理会话生命周期、沙箱环境、工具执行与事件流。开发者通过 RESTful 接口或 SDK 创建 Agent、Environment、Session 等资源，并以事件驱动方式与智能体交互。所有操作均基于工作空间隔离，需通过 API Key 鉴权。
|
||||
Managed Agents API 是百炼平台提供的智能体托管运行时服务，负责会话生命周期管理、沙箱环境调度、工具执行协调及事件流分发。开发者通过 REST 或 SDK 创建 Agent（含模型与系统提示）、Environment（运行沙箱）、Session（运行实例），再以事件驱动方式交互。所有资源均支持版本控制、归档与分页查询。
|
||||
|
||||
## 支持的模型与功能
|
||||
## 支持的模型/功能
|
||||
|
||||
- **模型支持**：当前仅支持 `qwen-plus` 等百炼托管大模型（详见 [API 总览与认证](../../raw/application-api-reference/managed-agents-api/managed-agents-api-overview.md)），模型 ID 通过 `model.id` 字段指定，不支持自定义模型接入。
|
||||
- **模型支持**：当前仅支持 `qwen-plus` 等百炼托管大模型（详见 [快速开始](../../raw/application-api-reference/managed-agents-api/managed-agents-quickstart.md) 中的端到端示例）；不支持自定义模型 ID 或外部模型接入。
|
||||
- **核心功能模块**：
|
||||
- **Agent**：封装模型、系统提示词、技能（Skill）与工具配置；支持版本化管理与软归档，每次更新自动递增 `version` 并采用乐观锁校验 [Agent](../../raw/application-api-reference/managed-agents-api/agent-api.md)。
|
||||
- **Environment**：定义沙箱类型（如 `"cloud"`）与预装依赖，独立于 Agent 管理，可被多个 Session 复用；运行中 Session 始终使用创建时绑定的环境快照 [Environment](../../raw/application-api-reference/managed-agents-api/environment-api.md)。
|
||||
- **Session**：一次运行实例，绑定 Agent 版本与 Environment 快照，状态机为 `idle → running → idle/terminated`；状态变更通过 SSE 事件流实时推送 [Session and Event](../../raw/application-api-reference/managed-agents-api/session-api.md)。
|
||||
- **File**：支持上传 ≤20 MB 文件，经安全审核后状态变为 `available` 方可挂载至沙箱或作为消息内容；单工作空间总容量上限 100 GB，保留期 30 天 [File](../../raw/application-api-reference/managed-agents-api/files-api.md)。
|
||||
- **Skill**：以 zip 包封装工具组合，上传后需通过安全扫描（状态：`checking` → `active`/`rejected`）；挂载到 Agent 时必须显式指定 `version`，不支持 `latest` 别名 [Skill](../../raw/application-api-reference/managed-agents-api/skills-api.md)。
|
||||
- **Agent**：封装模型、系统提示词、工具列表与 Skill 挂载配置；每次更新生成新版本，会话创建时锁定快照 [Agent](../../raw/application-api-reference/managed-agents-api/agent-api.md)。
|
||||
- **Environment**：定义沙箱类型（如 `"type": "cloud"`）与预装依赖，独立于 Agent 管理，可被多会话复用 [Environment](../../raw/application-api-reference/managed-agents-api/environment-api.md)。
|
||||
- **Skill**：以 zip 包形式封装工具组合，上传后需通过安全扫描（状态为 `active` 才可挂载），挂载时必须指定具体版本号，不支持 `latest` 别名 [Skill](../../raw/application-api-reference/managed-agents-api/skills-api.md)。
|
||||
- **File**：作为消息内容（图像/音频）或沙箱挂载文件使用；单文件上限 20 MB，审核状态为 `available` 后方可引用。
|
||||
|
||||
> **注意**：文档 1 中列出的 `/files` 端点支持 `multipart/form-data` 上传，但文档 6 明确要求单文件上限为 **20 MB**；若文档 1 未说明该限制，以文档 6 为准。
|
||||
> **注意**：文档 2 的 API 总览中列出 `/skills/{skill_id}/versions/{version}/download` 端点返回 OSS 预签名 URL，但文档 7 明确说明该接口路径为 `/skills/{skill_id}/versions/{version}/content`（非 `/download`）。实际应以文档 7 的 `GET /skills/{skill_id}/versions/{version}/content` 为准。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **Endpoint**：`https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio`，其中 `workspace_id`（如 `ws_xxxxxxxxxxxx`）和 `region`（当前仅支持 `cn-beijing`）为必填。
|
||||
- **鉴权**：所有请求需在 Header 中携带 `Authorization: Bearer <your-api-key>`。
|
||||
- **分页参数**：列表接口（如 `/agents`, `/sessions`）支持 `limit`（默认 20，最大 100）和 `page`（首次不传，后续传上一次响应的 `next_page`）。
|
||||
- **Agent 创建关键字段**：`name`（字符串）、`model.id`（如 `"qwen-plus"`）、`system`（系统提示词）、`skills`（技能 ID 列表，每个需已处于 `active` 状态）。
|
||||
- **Session 创建关键字段**：`agent`（Agent ID）、`environment_id`（Environment ID）；创建后即进入 `idle` 状态。
|
||||
- **Event 发送格式**：`POST /sessions/{session_id}/events` 请求体中 `input` 为消息数组，每条消息含 `role`（`user`/`assistant`）、`type`（`message`）、`content`（文本或富媒体数组）。
|
||||
- **认证参数**：全部请求需在 Header 中携带 `Authorization: Bearer <your-api-key>`，API Key 须归属目标工作空间。
|
||||
- **Endpoint 构造**：`https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio`，其中 `region` 当前仅支持 `cn-beijing`。
|
||||
- **Agent 创建参数**：
|
||||
- `model.id`：必需，如 `"qwen-plus"`；
|
||||
- `system`：必需，系统提示词字符串；
|
||||
- `skills`：可选，数组，每个元素为 `{ "id": "skl_xxx", "version": 1 }`。
|
||||
- **Environment 创建参数**：`config.type` 必需，取值 `"cloud"`（云沙箱）或 `"local"`（暂未开放）。
|
||||
- **Session 创建参数**：`agent`（Agent ID）与 `environment_id`（Environment ID）均为必需字段。
|
||||
- **Event 发送参数**：`input` 为消息数组，每条消息需含 `role`（`"user"` 或 `"assistant"`）、`type`（`"message"`）、`content`（文本或富媒体数组）。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **初始化**：设置环境变量 `DASHSCOPE_API_KEY` 和 `AGENTSTUDIO_URL`（按工作空间与地域拼装），或通过 SDK 构造 Client（Python SDK ≥ v1.26.2，Java SDK ≥ v2.22.24）[API 总览与认证](../../raw/application-api-reference/managed-agents-api/managed-agents-api-overview.md)。
|
||||
2. **资源创建**（通常一次性）：
|
||||
- 调用 `POST /agents` 创建 Agent；
|
||||
- 调用 `POST /environments` 创建 Environment；
|
||||
3. **会话执行**（每次任务）：
|
||||
- 调用 `POST /sessions` 创建 Session（绑定 Agent 与 Environment）；
|
||||
- 调用 `POST /sessions/{session_id}/events` 发送用户消息；
|
||||
- 调用 `GET /sessions/{session_id}/events/stream` 建立 SSE 连接，监听 `session_status` 变更及 `message` 事件，直至收到 `idle` 或 `terminated`。
|
||||
4. **SDK 示例**：Python 中使用 `dashscope.agentstudio.Client`，Java 中使用 `AgentStudioClient`，均提供 `agents.create()`、`sessions.create()`、`sessions.events.send()` 和 `sessions.events.stream()` 等高层封装方法 [快速开始](../../raw/application-api-reference/managed-agents-api/managed-agents-quickstart.md)。
|
||||
|
||||
> **注意**：文档 2 的 Bash 示例中 `curl -X POST ... /sessions/{session_id}/events` 发送消息后，需主动调用 `/events/stream` 订阅；而 Python/Java SDK 的 `stream()` 方法内部已处理长连接与自动重连，推荐优先使用 SDK。
|
||||
1. **初始化**：导出 `DASHSCOPE_API_KEY` 与 `AGENTSTUDIO_URL` 环境变量（见 [快速开始](../../raw/application-api-reference/managed-agents-api/managed-agents-quickstart.md)）；
|
||||
2. **资源准备**（通常一次性）：
|
||||
- 调用 `POST /agents` 创建并复用 Agent；
|
||||
- 调用 `POST /environments` 创建并复用 Environment；
|
||||
- （可选）调用 `POST /files` 上传文件，待 `status="available"` 后使用；
|
||||
- （可选）调用 `POST /skills` 创建 Skill 并上传版本，待 `status="active"` 后挂载至 Agent；
|
||||
3. **会话执行**（按需高频）：
|
||||
- 调用 `POST /sessions` 绑定 Agent 与 Environment，获取 `session_id`；
|
||||
- 调用 `POST /sessions/{session_id}/events` 提交用户消息；
|
||||
- 调用 `GET /sessions/{session_id}/events/stream` 建立 SSE 连接，监听 `session_status`（`idle`/`running`/`terminated`）及 `message` 事件；
|
||||
4. **SDK 接入**：Python SDK v1.26.2+ 与 Java SDK v2.22.24+ 已完整封装上述流程，推荐优先使用（见 [快速开始](../../raw/application-api-reference/managed-agents-api/managed-agents-quickstart.md) 中的 SDK 示例）。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域限制**：API 当前仅支持 `cn-beijing` 地域，其他地域 Endpoint 将返回 404。
|
||||
- **配额限制**：
|
||||
- 单文件上传上限 20 MB，工作空间总存储 100 GB，文件保留期 30 天；
|
||||
- Session 事件历史默认保留 7 天（具体策略以控制台为准）；
|
||||
- Skill zip 包大小建议 ≤50 MB（虽未明文限制，但过大易导致扫描超时）。
|
||||
- **状态一致性**：
|
||||
- Agent/Environment 更新为全量替换，缺省字段视为清空；已运行的 Session 不受更新影响；
|
||||
- File/Skill 上传后需等待 `status` 变为 `available`/`active` 后方可使用，直接引用 `checking` 状态资源将失败。
|
||||
- **错误处理**：
|
||||
- 所有响应含 `x-request-id`，提工单时务必提供；
|
||||
- 乐观锁冲突（如 Agent 更新时 `version` 不匹配）返回 HTTP 409；
|
||||
- 文件审核失败（`rejected`/`type_rejected`）或 Skill 扫描失败（`rejected`）需检查 `error_info` 字段定位问题。
|
||||
|
||||
- **归档行为**：Agent、Environment、Session 的归档均为软操作（记录 `archived_at`），不影响已存在会话，但禁止用于新建会话；删除（`DELETE`）为硬操作，不可恢复。
|
||||
- **配额限制**：单文件直传 ≤ 20 MB；工作空间总文件容量 ≤ 100 GB；文件保留期 30 天，超期可能被自动清理（见 [File](../../raw/application-api-reference/managed-agents-api/files-api.md)）。
|
||||
- **状态机约束**：
|
||||
- Session 状态为 `idle` 时才可接收新事件；`running` 状态下重复提交事件将被拒绝；
|
||||
- `terminated` 为终态，不可恢复；归档操作（`POST /sessions/{session_id}/archive`）会将其置为 `terminated`。
|
||||
- **版本与快照**：
|
||||
- Agent 更新采用乐观锁，请求体必须包含当前 `version` 字段，否则返回 409；
|
||||
- Environment 更新不影响已绑定会话，其内部使用绑定时刻的快照；
|
||||
- Skill 新版本上传不影响已挂载旧版本的 Agent。
|
||||
- **安全性**：
|
||||
- File 与 Skill 均需通过安全审核（`checking` → `available`/`active`），未通过者不可使用；
|
||||
- 所有工具调用均在隔离沙箱中执行，禁止访问宿主机或网络（除非显式配置白名单）。
|
||||
- **调试建议**：所有响应头含 `x-request-id`，提工单时务必提供，便于平台侧快速定位问题。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [API 总览与认证](../../raw/application-api-reference/managed-agents-api/managed-agents-api-overview.md)
|
||||
- [快速开始](../../raw/application-api-reference/managed-agents-api/managed-agents-quickstart.md)
|
||||
- [API 总览与认证](../../raw/application-api-reference/managed-agents-api/managed-agents-api-overview.md)
|
||||
- [Agent](../../raw/application-api-reference/managed-agents-api/agent-api.md)
|
||||
- [Session and Event](../../raw/application-api-reference/managed-agents-api/session-api.md)
|
||||
- [Environment](../../raw/application-api-reference/managed-agents-api/environment-api.md)
|
||||
- [File](../../raw/application-api-reference/managed-agents-api/files-api.md)
|
||||
- [Session and Event](../../raw/application-api-reference/managed-agents-api/session-api.md)
|
||||
- [Skill](../../raw/application-api-reference/managed-agents-api/skills-api.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,42 +1,43 @@
|
||||
# model production
|
||||
|
||||
`model production` 是百炼平台中将训练/微调完成的模型转化为可调用在线服务的核心流程，涵盖模型部署与微调任务管理两大能力。开发者可通过统一 API 接口触发、监控和管理生产级模型生命周期。该模块不提供训练基础设施调度，仅负责模型服务化与微调作业编排。
|
||||
`model production` 是百炼平台中用于将模型投入实际应用的核心能力集合，涵盖从微调训练到在线服务部署的完整生命周期。开发者可通过 API 或控制台完成模型定制与发布，支持快速迭代和灰度发布。该能力依赖于底层计算资源调度与版本化管理机制。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **模型部署**：支持将已完成微调或通过 [模型导入](../../raw/model-api-reference/model-production/deployments-api.md) 流程上传的模型，发布为 HTTP 可访问的在线推理端点。
|
||||
- **模型微调**：支持基于预置基座模型（如 Qwen 系列）启动监督微调（SFT）任务，输入标注数据集后异步执行训练，并自动产出可部署模型版本。
|
||||
- **功能边界**：当前不支持强化学习（RLHF）微调、多模态联合微调或跨模型架构迁移微调。相关能力请参考 [模型调优](../../raw/model-api-reference/model-production/fine-tuning-jobs-api.md) 文档说明。
|
||||
- **微调训练（Fine-tuning）**：支持基于预训练大模型（如 Qwen 系列）进行监督微调，适配特定任务（如客服对话、金融问答）。训练数据需为 JSONL 格式，每条样本包含 `messages` 字段（[模型调优](../../raw/model-api-reference/model-production/fine-tuning-jobs-api.md)）。
|
||||
- **模型部署（Deployment）**：支持将微调完成的模型或通过 `import_model` 接口导入的第三方模型（如 Hugging Face 格式）部署为 HTTP 可调用的在线推理服务，提供自动扩缩容与健康检查（[模型部署](../../raw/model-api-reference/model-production/deployments-api.md)）。
|
||||
- **版本管理**：每个微调任务生成唯一 `fine_tuning_job_id`，对应产出模型版本；部署时需显式指定 `model_version_id`，确保可追溯性。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `model_id` | string | 是 | 模型唯一标识符，来自微调任务输出或导入模型列表 |
|
||||
| `endpoint_name` | string | 是 | 部署后生成的全局唯一服务域名前缀（如 `my-llm-v1`），需符合 DNS 子域名规范（小写字母、数字、连字符，长度 3–32） |
|
||||
| `instance_type` | string | 否 | 指定 GPU 实例规格（如 `gpu.2xlarge`），未指定时使用默认规格；不同 region 可用规格以 [模型部署](../../raw/model-api-reference/model-production/deployments-api.md) 中的 `list_instance_types` 接口为准 |
|
||||
| `max_concurrency` | integer | 否 | 单实例最大并发请求数，默认值为 `10`，最大支持 `100` |
|
||||
| 参数 | 说明 | 示例值 |
|
||||
|------|------|--------|
|
||||
| `base_model` | 微调所基于的基座模型 ID | `"qwen2-7b"` |
|
||||
| `training_file_id` | 训练数据文件 ID（需先通过 `/files/upload` 上传） | `"file_abc123"` |
|
||||
| `deployment_name` | 部署服务唯一标识符，全局唯一且不可修改 | `"prod-faq-v2"` |
|
||||
| `instance_type` | 推理实例规格，影响并发与延迟 | `"gpu.2xlarge"` |
|
||||
|
||||
> **注意**：文档 1 中称“支持导入模型部署”，但文档 2 未明确说明导入模型是否可用于微调。实际验证表明，仅通过 [模型导入](../../raw/model-api-reference/model-production/deployments-api.md) 上传的模型**不可直接用于微调任务**，必须先关联至支持微调的基座模型族（如 `qwen2-7b`），否则 `fine_tuning_jobs` 创建将返回 `400 InvalidBaseModel` 错误。
|
||||
> **注意**：文档 1 中未明确 `base_model` 的可选值范围，而文档 2 的 `/deployments` 接口文档（见 [模型部署](../../raw/model-api-reference/model-production/deployments-api.md)）补充了 `qwen2-7b`、`qwen2-57b` 和 `llama3-8b` 三类已验证支持型号，建议以该文档为准。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **启动微调**：调用 `POST /v1/fine_tuning_jobs`，传入 `training_file_id`、`base_model` 和超参配置；
|
||||
2. **等待完成**：轮询 `GET /v1/fine_tuning_jobs/{job_id}` 直至 `status == "succeeded"`，获取输出 `model_id`；
|
||||
3. **部署服务**：调用 `POST /v1/deployments`，传入上一步的 `model_id` 与 `endpoint_name`；
|
||||
4. **调用推理**：使用返回的 `endpoint_url` 发送 `POST /v1/chat/completions` 请求（需携带 `Authorization: Bearer <api_key>`）。
|
||||
1. **微调流程**：
|
||||
- 上传训练数据 → 创建微调任务（`POST /fine_tuning/jobs`）→ 轮询 `status` 直至 `succeeded` → 获取产出 `model_version_id`
|
||||
2. **部署流程**：
|
||||
- 调用 `POST /deployments`，传入 `model_version_id`、`deployment_name` 与 `instance_type` → 等待 `status: "ready"` → 使用 `endpoint_url` 发起推理请求
|
||||
|
||||
所有操作均需携带 `Authorization: Bearer <api_key>`，且请求体必须为 `application/json`。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- 单个微调任务最长运行时限为 72 小时，超时自动终止并标记为 `failed`；
|
||||
- 同一 `endpoint_name` 在全平台唯一，重名部署请求将返回 `409 Conflict`；
|
||||
- 部署后模型默认启用自动扩缩容（min=1, max=5），手动调整需通过 `PATCH /v1/deployments/{id}` 修改 `min_instances`/`max_instances`；
|
||||
- 微调任务日志仅保留 30 天，部署日志保留 7 天，过期后不可恢复；
|
||||
- 所有模型部署均强制启用 HTTPS，不支持 HTTP 明文访问。
|
||||
- 单次微调任务最大训练时长为 72 小时，超时自动终止；若需更长训练周期，须拆分为多阶段微调（[模型调优](../../raw/model-api-reference/model-production/fine-tuning-jobs-api.md)）。
|
||||
- 每个部署服务默认最大并发请求数为 100，超出后返回 `429 Too Many Requests`；可通过工单申请提升配额。
|
||||
- 微调任务一旦提交不可取消或修改参数；部署服务删除后，关联模型版本仍保留在仓库中，但无法再被部署（除非重新创建同名 deployment）。
|
||||
- > **注意**：文档 1 声称“支持任意开源模型微调”，但文档 2 明确限定仅支持平台预置基座模型（见 [模型部署](../../raw/model-api-reference/model-production/deployments-api.md)），自定义基座模型暂不支持部署，此为关键兼容性约束。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [模型部署](../../raw/model-api-reference/model-production/deployments-api.md)
|
||||
- [模型调优](../../raw/model-api-reference/model-production/fine-tuning-jobs-api.md)
|
||||
- [模型部署](../../raw/model-api-reference/model-production/deployments-api.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,68 +1,57 @@
|
||||
# [more](more.md) about models
|
||||
|
||||
百炼平台提供丰富的模型调用能力，涵盖同步/[异步任务](../concepts/asynchronous-task.md)处理、多模态文件支持、子空间隔离、连接优化及安全凭证管理。本文面向开发者，系统梳理核心能力、关键参数、使用方式及限制，帮助您高效、稳定地集成模型服务。
|
||||
阿里云百炼平台提供多种模型调用方式与配套能力，涵盖同步/异步任务处理、多业务空间隔离、文件临时托管、连接复用优化及事件驱动通知等核心场景。本文面向开发者，系统梳理关键能力、参数约束、使用路径及注意事项，帮助构建稳定、高效、可扩展的模型集成方案。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
百炼支持多种模型类型与调用模式：
|
||||
- **标准大模型**（如 `qwen-plus`、`qwen-vl-plus`）和**调优后专属模型**均可通过 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)或 DashScope 原生接口调用；
|
||||
- **长耗时模型**（如文生图、文生视频、语音识别等）统一采用**[异步任务](../concepts/asynchronous-task.md)机制**，需先创建任务再查询结果；
|
||||
- **多模态模型**（图像、音频、视频）依赖外部文件输入，平台提供免费临时存储并返回 `oss://` 格式 URL；
|
||||
- 所有模型均支持在**默认业务空间**或**子业务空间**中调用，子空间可实现权限隔离与费用分账 [子业务空间的模型调用](../../raw/model-api-reference/more-about-models/model-calling-in-sub-workspace.md)；
|
||||
- [异步任务](../concepts/asynchronous-task.md)完成通知支持**事件总线主动推送**（HTTP 回调或 RocketMQ），替代轮询，提升实时性并规避限流 [通过HTTP回调URL或MQ接收异步任务完成通知](../../raw/model-api-reference/more-about-models/async-task-api.md)。
|
||||
|
||||
> **注意**：文档 4 中明确指出“调用在阿里云百炼[调优](https://help.aliyun.com/zh/model-studio/model-training-overview)并部署的模型，**无需模型调用授权**”，但文档 3 的“前提条件”仅要求“获取API Key”，未提及子空间模型授权例外。实际开发中，若在子空间调用调优模型失败，请优先检查是否遗漏了该空间的模型调用权限配置——此为常见误配点。
|
||||
百炼支持标准大语言模型（如 `qwen-plus`）、[多模态](../concepts/multi-modal.md)模型（如 `qwen-vl-plus`）、图像生成（如 `wanx2.1-t2i-turbo`）、视频生成（如 `wanx2.1-kf2v-plus`）及语音识别（如 `paraformer-16k-1`）等。不同模型适用不同调用模式：
|
||||
- **同步模型**（如文本生成）直接返回结果；
|
||||
- **异步模型**（如图像/视频生成）需通过 [异步任务管理 API](../../raw/model-api-reference/more-about-models/manage-asynchronous-tasks.md) 创建任务、轮询或订阅事件获取结果；
|
||||
- **子业务空间模型**（如非默认 Workspace 中部署的 `qwen-plus`）必须使用该空间专属 API Key，并显式配置对应地域的 `base_url`（北京为 `https://dashscope.aliyuncs.com/compatible-mode/v1`，新加坡为 `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`）[子业务空间的模型调用](../../raw/model-api-reference/more-about-models/model-calling-in-sub-workspace.md)。
|
||||
> **注意**：文档 3 明确指出“调用在阿里云百炼[调优](https://help.aliyun.com/zh/model-studio/model-training-overview)并部署的模型，**无需模型调用授权**”，但文档 2 的异步任务接口描述中未区分标准模型与调优模型的权限逻辑，实际调用时请以控制台中该子空间的模型授权配置为准。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 说明 | 取值范围/示例 | 来源 |
|
||||
|------|------|----------------|------|
|
||||
| `task_id` | 异步任务唯一标识符，用于查询或取消任务 | UUID 格式字符串，如 `a8532587-...-0c46b17950d1` | [异步任务管理 API](../../raw/model-api-reference/more-about-models/manage-asynchronous-tasks.md) |
|
||||
| `expire_in_seconds` | 临时 API Key 有效期 | `[1, 1800]` 秒（默认 60 秒） | [生成临时API Key](../../raw/model-api-reference/more-about-models/generate-temporary-api-key.md) |
|
||||
| `model_name` | 文件上传时必需指定的模型名，与后续调用模型严格一致 | 如 `qwen-vl-plus`, `wanx2.1-t2i-turbo` | [上传本地文件获取临时URL](../../raw/model-api-reference/more-about-models/get-temporary-file-url.md) |
|
||||
| `X-DashScope-OssResourceResolve: enable` | 使用 `oss://` URL 时**必须**添加的请求头 | 字符串字面量 | [上传本地文件获取临时URL](../../raw/model-api-reference/more-about-models/get-temporary-file-url.md) |
|
||||
| `connectionPoolSize` / `limit` | Java/Python SDK 连接池最大连接数 | Java 默认 32，Python `aiohttp.TCPConnector.limit` 默认 100 | [DashScope SDK连接复用配置](../../raw/model-api-reference/more-about-models/connection-multiplexing-configuration.md) |
|
||||
| 参数 | 说明 | 约束 | 来源 |
|
||||
|------|------|------|------|
|
||||
| `expire_in_seconds` | 临时 API Key 有效期 | `[1, 1800]` 秒，默认 60 秒 | [生成临时API Key](../../raw/model-api-reference/more-about-models/generate-temporary-api-key.md) |
|
||||
| `task_id` | 异步任务唯一标识 | UUID 格式，用于查询/取消任务 | [异步任务管理 API](../../raw/model-api-reference/more-about-models/manage-asynchronous-tasks.md) |
|
||||
| `model_name` | 文件上传时绑定的模型名 | 必须与后续模型调用的 `model` 参数一致，否则报错 | [上传本地文件获取临时URL](../../raw/model-api-reference/more-about-models/get-temporary-file-url.md) |
|
||||
| `X-DashScope-OssResourceResolve: enable` | 使用 `oss://` URL 时必需的请求头 | 缺失将导致模型调用失败 | [上传本地文件获取临时URL](../../raw/model-api-reference/more-about-models/get-temporary-file-url.md) |
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 1. 调用流程选择
|
||||
- **短耗时模型**（文本生成等）：直接同步调用，推荐使用 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)（`/compatible-mode/v1/chat/completions`）或 DashScope 原生接口（`/api/v1/services/aigc/text-generation/generation`）。
|
||||
- **长耗时模型**（图像/视频生成等）：必须走异步流程：
|
||||
(1) 发起任务 → 获取 `task_id`；
|
||||
(2) 通过 `GET /api/v1/tasks/{task_id}` 查询结果；
|
||||
(3) 或配置事件总线接收 `dashscope:System:AsyncTaskFinish` 事件，避免轮询 [通过HTTP回调URL或MQ接收异步任务完成通知](../../raw/model-api-reference/more-about-models/async-task-api.md)。
|
||||
### 1. 安全调用（不可信环境）
|
||||
在浏览器或 App 中调用模型前，后端应通过 `POST https://dashscope.aliyuncs.com/api/v1/tokens?expire_in_seconds=1800` 生成临时 API Key，并将其透传给前端。该 Key 继承父 Key 全部权限，且**到期自动失效，不可手动删除** [生成临时API Key](../../raw/model-api-reference/more-about-models/generate-temporary-api-key.md)。
|
||||
|
||||
### 2. 多模态文件处理
|
||||
- 上传前：确认模型支持该文件类型，并确保 `model_name` 与调用时完全一致；
|
||||
- 上传后：获得 `oss://...` URL，**必须在模型调用请求头中添加 `X-DashScope-OssResourceResolve: enable`**；
|
||||
- 注意：文件有效期仅 48 小时，生产环境应使用 OSS 等长期存储方案。
|
||||
### 2. [多模态](../concepts/multi-modal.md)[文件处理](../concepts/file-processing.md)
|
||||
调用 `qwen-vl-plus` 等模型前，需先上传本地文件获取 `oss://` URL：
|
||||
- 调用 `GET https://dashscope.aliyuncs.com/api/v1/uploads?action=getPolicy&model=qwen-vl-plus` 获取上传策略；
|
||||
- 按策略向 OSS 上传文件；
|
||||
- 得到 URL 后，在模型请求 Header 中**必须添加** `X-DashScope-OssResourceResolve: enable`。
|
||||
|
||||
### 3. 子业务空间调用
|
||||
- 必须使用**该子空间生成的 API Key**；
|
||||
- 调用标准模型需提前在子空间内授权；调优模型则自动继承空间权限；
|
||||
- 地域差异：北京地域使用 `https://dashscope.aliyuncs.com/...`，新加坡地域需替换为 `{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com`。
|
||||
### 3. 高并发连接优化
|
||||
- **Java SDK**：通过 `Constants.connectionConfigurations` 配置连接池（如 `connectionPoolSize=256`, `readTimeout=300`）；
|
||||
- **Python SDK**：同步场景用 `requests.Session()`，异步场景用 `aiohttp.TCPConnector(limit=100)` 实现复用 [DashScope SDK连接复用配置](../../raw/model-api-reference/more-about-models/connection-multiplexing-configuration.md)。
|
||||
|
||||
### 4. 连接优化（高并发场景）
|
||||
- **Java SDK**：通过 `Constants.connectionConfigurations` 配置连接池参数（如 `connectionPoolSize=256`）；
|
||||
- **Python SDK**：同步调用传入 `requests.Session()`，异步调用传入 `aiohttp.ClientSession(connector=...)`；
|
||||
- 所有配置均需在首次调用前完成初始化。
|
||||
### 4. 异步任务结果获取
|
||||
- **轮询**：调用 `GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}`，QPS 限 20；
|
||||
- **事件驱动（推荐）**：在事件总线配置规则，监听 `dashscope:System:AsyncTaskFinish` 事件，目标设为 HTTP 回调或 RocketMQ，避免轮询限流与资源浪费 [通过HTTP回调URL或MQ接收异步任务完成通知](../../raw/model-api-reference/more-about-models/async-task-api.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **临时文件存储**：单文件 ≤ 1 GB；上传限流 100 QPS（按主账号+模型维度）；**严禁用于生产环境或压测** [上传本地文件获取临时URL](../../raw/model-api-reference/more-about-models/get-temporary-file-url.md)；
|
||||
- **临时 API Key**：继承父 Key 全部权限，无法手动删除，到期自动失效；各地域 Endpoint 不互通；
|
||||
- **异步任务查询**：流量限制 20 QPS；任务数据保留约 24 小时（以具体模型文档为准）；仅支持取消 `PENDING` 状态任务；
|
||||
- **子空间模型调用**：API Key 与空间强绑定，跨空间调用将返回鉴权错误；
|
||||
- **连接复用**：Java SDK 默认启用连接池，Python SDK 需显式传入 Session 实例，否则每次调用新建连接；
|
||||
- **地域一致性**：API Key、Endpoint、事件总线地域（如 `cn-beijing`）三者必须匹配，否则请求失败。
|
||||
- **临时文件**：`oss://` URL 有效期严格为 **48 小时**，超时自动清理；文件与主账号、模型强绑定，不可跨账号/模型复用；上传限流 **100 QPS（按主账号+模型维度）**，**禁止用于生产环境或压测**，生产环境应使用 OSS [上传本地文件获取临时URL](../../raw/model-api-reference/more-about-models/get-temporary-file-url.md)。
|
||||
- **异步任务生命周期**：任务完成后保留 **24 小时**（具体以各模型文档为准），超时后无法查询；仅 `PENDING` 状态任务可取消 [异步任务管理 API](../../raw/model-api-reference/more-about-models/manage-asynchronous-tasks.md)。
|
||||
- **地域一致性**：API Key、Endpoint、Workspace ID 必须匹配同一地域（北京/新加坡/弗吉尼亚），混用将导致 `InvalidApiKey` 错误 [生成临时API Key](../../raw/model-api-reference/more-about-models/generate-temporary-api-key.md)。
|
||||
- **子空间权限**：调用标准模型（如 `qwen-plus`）前，需在子业务空间中**显式授权**该模型；而调优部署的模型仅允许其所在空间的 API Key 调用，无需额外授权 [子业务空间的模型调用](../../raw/model-api-reference/more-about-models/model-calling-in-sub-workspace.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [生成临时API Key](../../raw/model-api-reference/more-about-models/generate-temporary-api-key.md)
|
||||
- [通过HTTP回调URL或MQ接收异步任务完成通知](../../raw/model-api-reference/more-about-models/async-task-api.md)
|
||||
- [异步任务管理 API](../../raw/model-api-reference/more-about-models/manage-asynchronous-tasks.md)
|
||||
- [子业务空间的模型调用](../../raw/model-api-reference/more-about-models/model-calling-in-sub-workspace.md)
|
||||
- [上传本地文件获取临时URL](../../raw/model-api-reference/more-about-models/get-temporary-file-url.md)
|
||||
- [DashScope SDK连接复用配置](../../raw/model-api-reference/more-about-models/connection-multiplexing-configuration.md)
|
||||
- [通过HTTP回调URL或MQ接收异步任务完成通知](../../raw/model-api-reference/more-about-models/async-task-api.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,64 +1,58 @@
|
||||
# [more](more.md) models
|
||||
|
||||
百炼平台提供一系列面向垂直场景的专用大模型，覆盖意图理解、深度研究、OCR识别、GUI自动化、机器翻译和法律推理等能力。这些模型均基于通义千问基座，通过领域数据精调与架构优化，在特定任务上显著优于通用模型。开发者可通过 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)或 DashScope SDK 调用，支持多地域部署与业务空间专属域名接入。
|
||||
百炼平台提供一系列面向垂直场景的专用大模型，覆盖法律、意图理解、机器翻译、深度研究、OCR图文识别和GUI自动化等方向。这些模型在通用大模型基础上进行了领域精调或架构增强，支持通过 DashScope SDK 或 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)调用，适用于高精度、低延迟、[多模态](../concepts/multi-modal.md)等特定业务需求。
|
||||
|
||||
## 支持的模型/功能
|
||||
## 支持的模型与功能
|
||||
|
||||
当前 `more models` 类别下已开放以下专用模型：
|
||||
| 模型名称 | 用途 | 关键能力 | 文档引用 |
|
||||
|----------|------|-----------|-----------|
|
||||
| `farui-plus` | 法律行业大模型 | 法律问答、案情分析、文书生成、合同审查、RAG检索增强 | [通义法睿大语言模型](../../raw/model-api-reference/more-models/tongyi-farui-api.md) |
|
||||
| `tongyi-intent-detect-v3` | 意图理解 | 百毫秒级意图识别、工具调用解析（INTENT_MODE）、单标签分类 | [意图理解能力](../../raw/model-api-reference/more-models/intent-detect-capability.md) |
|
||||
| `qwen-mt-plus` | 机器翻译 | 多语言互译、术语干预、翻译记忆（TM）、领域提示 | [Qwen-MT API参考](../../raw/model-api-reference/more-models/qwen-mt-api.md) |
|
||||
| `qwen-deep-research` | 深度研究 | 两阶段交互式研究（反问确认 + 网络搜索 + 报告生成）、带引用溯源的结构化输出 | [Qwen-Deep-Research API 参考](../../raw/model-api-reference/more-models/qwen-deep-research-api.md) |
|
||||
| `qwen3.5-ocr` | 图文识别 | 多格式图像文字提取、结构化信息抽取（如车票字段）、支持 Prompt 控制输出格式 | [Qwen-OCR API参考](../../raw/model-api-reference/more-models/qwen-vl-ocr-api-reference.md) |
|
||||
| `gui-plus-2026-02-26` | GUI 自动化 | 基于截图的桌面操作（鼠标/键盘/等待/终止）、[函数调用](../concepts/function-calling.md)驱动界面交互 | [GUI-Plus API参考](../../raw/model-api-reference/more-models/gui-plus-interface-interaction-model.md) |
|
||||
|
||||
- **意图理解模型**：`tongyi-intent-detect-v3`，支持毫秒级意图识别与[函数调用](../concepts/function-calling.md)生成，适用于对话路由、智能助手等场景。详情见 [意图理解能力](../../raw/model-api-reference/more-models/intent-detect-capability.md)。
|
||||
- **深度研究模型**：`qwen-deep-research`，支持两阶段交互式研究（反问确认 + 网络检索增强分析），仅限华北2（北京）地域调用，暂不支持 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md) [Qwen-Deep-Research API 参考](../../raw/model-api-reference/more-models/qwen-deep-research-api.md)。
|
||||
- **OCR识别模型**：`qwen3.5-ocr`，支持图文混合输入与结构化文本提取，兼容 OpenAI 多模态格式（含 `image_url` + `min_pixels`/`max_pixels` 参数）[Qwen-OCR API参考](../../raw/model-api-reference/more-models/qwen-vl-ocr-api-reference.md)。
|
||||
- **GUI自动化模型**：`gui-plus-2026-02-26`，专用于桌面界面操作，需配合 `computer_use` 工具调用及高分辨率图像输入（通过 `extra_body={"vl_high_resolution_images": true}` 启用）。
|
||||
- **机器翻译模型**：`qwen-mt-plus`，支持源/目标语言指定、术语干预、翻译记忆（TM）及领域提示，所有参数均通过 `extra_body.translation_options` 传递。
|
||||
- **法律推理模型**：`farui-plus`，上下文长度 12K，具备法律文书生成、案情分析、合同审查等能力，支持单轮/多轮对话与[流式输出](../concepts/streaming-output.md)。
|
||||
|
||||
> **注意**：文档 5 中重复列出了新加坡与美国地域的配置说明（两次“新加坡地域”、两次“美国（弗吉尼亚）地域”），属冗余内容，实际配置请以首次出现的条目为准。
|
||||
> **注意**：文档 4 明确指出 `qwen-deep-research` “仅支持华北2（北京）地域”且“暂不支持 Java SDK 与 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)”，而其他模型（如 `farui-plus`、`qwen-mt-plus`）均明确支持 Python/Java SDK 及 OpenAI 兼容模式。该限制需在集成时严格遵守，否则将导致调用失败。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 类型 | 说明 | 所属模型 |
|
||||
|------|------|------|----------|
|
||||
| `model` | string | 必选。模型名称，如 `tongyi-intent-detect-v3`、`qwen3.5-ocr` 等 | 全部 |
|
||||
| `messages` | array | 必选。按角色（`system`/`user`/`assistant`）组织的对话历史，支持 `text` 和 `image_url` 类型内容 | `qwen3.5-ocr`, `gui-plus-2026-02-26`, `qwen-mt-plus`, `farui-plus` |
|
||||
| `system` message 内容 | string | 控制行为模式的关键指令。例如：<br>- `tongyi-intent-detect-v3` 需包含 `Response in INTENT_MODE.` 或明确意图字典<br>- `gui-plus-2026-02-26` 需声明 `<tools>` 与 `<tool_call>` 响应格式 | `tongyi-intent-detect-v3`, `gui-plus-2026-02-26` |
|
||||
| `extra_body.translation_options` | object | `qwen-mt-plus` 专用，包含 `source_lang`, `target_lang`, `terms`, `tm_list` 等字段 | `qwen-mt-plus` |
|
||||
| `result_format="message"` | string | DashScope SDK 中必需显式设置，否则默认返回 `text` 格式（无 `choices` 结构） | `farui-plus`, `qwen-deep-research` |
|
||||
| `stream=True` + `incremental_output=True` | boolean | [流式输出](../concepts/streaming-output.md)必需组合，尤其 `farui-plus` 的 Java SDK 需使用 `streamCall` 接口 | `farui-plus` |
|
||||
所有模型均遵循统一参数范式，但部分模型支持扩展参数：
|
||||
|
||||
- **通用必选参数**：`model`（字符串，如 `"farui-plus"`）、`messages`（消息数组，含 `role` 和 `content`）
|
||||
- **扩展参数（按模型）**：
|
||||
- `qwen-mt-plus`：通过 `extra_body.translation_options` 传入 `source_lang`、`target_lang`、`terms`（术语表）、`tm_list`（翻译记忆）；
|
||||
- `qwen3.5-ocr`：`messages.content` 支持 `image_url` + `text` 混合输入，可指定 `min_pixels` / `max_pixels` 控制图像缩放；
|
||||
- `gui-plus-2026-02-26`：需在 `extra_body` 中设置 `vl_high_resolution_images: true` 以启用高分辨率截图处理；
|
||||
- `qwen-deep-research`：支持 `output_format` 参数，取值为 `model_detailed_report`（默认，约6000 [Token](../concepts/token.md)）或 `model_summary_report`（约1500–2000 [Token](../concepts/token.md)）；
|
||||
- `tongyi-intent-detect-v3`：依赖 `system` 消息中显式声明 `Response in INTENT_MODE.` 或意图字典格式，否则无法触发对应模式。
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 域名与认证
|
||||
- **强烈推荐迁移至业务空间专属域名**：华北2（北京）为 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`，新加坡为 `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com`，详见 [意图理解能力](../../raw/model-api-reference/more-models/intent-detect-capability.md) 和 [Qwen-OCR API参考](../../raw/model-api-reference/more-models/qwen-vl-ocr-api-reference.md) 中的迁移说明。
|
||||
- 所有模型均需有效 `DASHSCOPE_API_KEY`，建议配置至环境变量而非硬编码。
|
||||
- **强制使用业务空间专属域名**：华北2（北京）和新加坡地域必须使用 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com` 或 `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com`，旧域名 `dashscope.aliyuncs.com` 已不推荐（见[意图理解能力](../../raw/model-api-reference/more-models/intent-detect-capability.md)和[Qwen-MT API参考](../../raw/model-api-reference/more-models/qwen-mt-api.md)中的迁移说明）。
|
||||
- **API Key 配置**：必须通过环境变量 `DASHSCOPE_API_KEY` 设置，禁止硬编码；Java SDK 要求复用 `Generation` 对象并注意线程安全（见[通义法睿大语言模型](../../raw/model-api-reference/more-models/tongyi-farui-api.md)）。
|
||||
|
||||
### 调用协议选择
|
||||
- **[OpenAI 兼容接口](../concepts/openai-compatible-interface.md)**：适用于 `tongyi-intent-detect-v3`, `qwen3.5-ocr`, `gui-plus-2026-02-26`, `qwen-mt-plus`，需设置 `base_url` 并使用 `chat.completions.create`。
|
||||
- **DashScope SDK**：适用于 `qwen-deep-research`（强制）、`farui-plus`（推荐）、`tongyi-intent-detect-v3`（可选），需设置 `dashscope.base_http_api_url`（北京/新加坡）或 `Constants.baseHttpApiUrl`（Java）。
|
||||
|
||||
### 输入构造要点
|
||||
- **意图识别**：`system` 消息必须明确指示 `INTENT_MODE` 或意图字典；工具定义需 JSON 序列化后嵌入 [prompt](../guides/prompt.md)。
|
||||
- **OCR 与 GUI**：`user` 消息中 `content` 为数组，含 `{"type": "image_url", "image_url": {"url": "..."}, "min_pixels": ..., "max_pixels": ...}` 与 `{"type": "text", "text": "prompt"}`。
|
||||
- **翻译**：`translation_options` 必须置于 `extra_body`（Python/Node.js）或顶层请求体（curl）。
|
||||
- **深度研究**：严格遵循两阶段流程——先发起研究主题（无 `assistant` 消息），再将模型反问结果作为 `assistant` 消息传入第二轮请求。
|
||||
### 调用示例共性
|
||||
- 所有模型均支持[流式输出](../concepts/streaming-output.md)（`stream=True` / `X-DashScope-SSE: enable`），但 `qwen-deep-research` 必须分两步调用（先反问确认，再深入研究）；
|
||||
- `tongyi-intent-detect-v3` 的 `INTENT_MODE` 响应需用正则解析 `<tags>` / `<tool_call>` / `<content>` 三段式结构（见[意图理解能力](../../raw/model-api-reference/more-models/intent-detect-capability.md)）；
|
||||
- `qwen3.5-ocr` 和 `gui-plus-2026-02-26` 均要求 `messages.content` 为数组，包含 `image_url` 和 `text` 对象，不可仅传纯文本。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域限制**：`qwen-deep-research` 仅支持华北2（北京）地域；`farui-plus` 未明确地域限制，但示例代码均使用北京专属域名，建议优先选用北京地域。
|
||||
- **SDK 支持差异**：
|
||||
- `qwen-deep-research` **不支持 OpenAI 兼容接口**，仅 DashScope Python SDK 可用 [Qwen-Deep-Research API 参考](../../raw/model-api-reference/more-models/qwen-deep-research-api.md)。
|
||||
- `farui-plus` 的 Java SDK 需版本 ≥ 2.12.0，且 `Generation` 对象非线程安全。
|
||||
- **成本与配额**：`tongyi-intent-detect-v3` 提供开通后90天内100万 [Token](../concepts/token.md) 免费额度；`farui-plus` 输入成本为20元/百万 [Token](../concepts/token.md)，具体计费规则需查阅控制台限流文档。
|
||||
- **响应解析**：`tongyi-intent-detect-v3` 的 `INTENT_MODE` 输出需用正则解析 `<tags>`/<tool_call>/`<content>` 三段式结构；`qwen-deep-research` 响应含 `phase` 字段（如 `answer`, `WebResearch`），需按阶段处理 `extra.deep_research.references` 等字段。
|
||||
- **图像预处理**：`qwen3.5-ocr` 与 `gui-plus-2026-02-26` 均支持 `min_pixels`/`max_pixels` 自动缩放，但 `gui-plus` 必须启用 `vl_high_resolution_images` 才能正确解析桌面截图细节。
|
||||
- **地域限制**：`qwen-deep-research` 仅限华北2（北京）地域，其他地域调用将失败；`qwen-mt-plus` 和 `qwen3.5-ocr` 支持北京、新加坡、美国（弗吉尼亚）三地，但各地区 API Key 不互通。
|
||||
- **SDK 限制**：`qwen-deep-research` 当前仅支持 Python DashScope SDK，不支持 Java SDK 和 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)（见[Qwen-Deep-Research API 参考](../../raw/model-api-reference/more-models/qwen-deep-research-api.md)）。
|
||||
- **成本与配额**：`tongyi-intent-detect-v3` 提供 100 万 [Token](../concepts/token.md) 免费额度（开通后 90 天内有效），其余模型按实际 Token 数计费；`farui-plus` 输入/输出成本分别为 20 元/百万 Token（见[通义法睿大语言模型](../../raw/model-api-reference/more-models/tongyi-farui-api.md)）。
|
||||
- **流式响应解析**：`qwen-deep-research` 的流式响应包含 `phase` 字段（如 `"ResearchPlanning"`、`"WebResearch"`、`"answer"`），需据此区分阶段并处理 `extra.deep_research.references` 等结构化数据。
|
||||
- **图像处理约束**：`qwen3.5-ocr` 和 `gui-plus-2026-02-26` 对输入图像有像素阈值（`min_pixels`/`max_pixels`），超出范围将自动缩放，需在请求中显式配置以避免失真。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [通义法睿大语言模型](../../raw/model-api-reference/more-models/tongyi-farui-api.md)
|
||||
- [意图理解能力](../../raw/model-api-reference/more-models/intent-detect-capability.md)
|
||||
- [Qwen-MT API参考](../../raw/model-api-reference/more-models/qwen-mt-api.md)
|
||||
- [Qwen-Deep-Research API 参考](../../raw/model-api-reference/more-models/qwen-deep-research-api.md)
|
||||
- [Qwen-OCR API参考](../../raw/model-api-reference/more-models/qwen-vl-ocr-api-reference.md)
|
||||
- [GUI-Plus API参考](../../raw/model-api-reference/more-models/gui-plus-interface-interaction-model.md)
|
||||
- [Qwen-MT API参考](../../raw/model-api-reference/more-models/qwen-mt-api.md)
|
||||
- [通义法睿大语言模型](../../raw/model-api-reference/more-models/tongyi-farui-api.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,42 +1,41 @@
|
||||
# more
|
||||
|
||||
`more` 是百炼平台中一组面向高级用例的扩展能力集合，涵盖服务权限管理、安全认证机制与知识库精细化检索等功能。它不构成独立 API 服务，而是以配套机制形式支撑工作流编排、安全存储、模型监控、RAG 等核心场景。开发者需结合具体功能模块（如知识库、工作流、安全存储）按需启用和配置。
|
||||
`more` 是百炼平台中一组支撑性能力的统称，涵盖临时凭证管理、服务关联角色（SLR）授权、以及知识库高级检索过滤等功能。这些能力不直接参与模型推理，但为安全调用、跨云服务集成和精准语义检索提供关键基础设施支持。开发者需根据具体场景选择并正确配置对应机制。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
`more` 本身不提供模型，而是为以下功能提供底层支撑能力：
|
||||
|
||||
- **服务关联角色（SLR）**：自动创建并绑定 RAM 角色，使百炼可安全访问外部云资源（如 FC、OSS、ADB-PG、MNS、SLS、CMS、OpenTelemetry、DTS、CPFS、内容安全）。例如，工作流调用函数计算节点依赖 `AliyunServiceRoleForSFMAccessFC`，知识库对接 ADB-PG 依赖 `AliyunServiceRoleForSFMAccessADB` [服务关联角色](../../raw/application-api-reference/more/bailian-service-linked-role.md)。
|
||||
- **临时 API Key 生成**：用于在不可信前端环境（如浏览器、App）中安全调用模型服务，避免永久密钥泄露。该能力通过 `/api/v1/tokens` 接口提供，由后端服务代理调用 [生成临时API Key](../../raw/application-api-reference/more/application-obtain-temporary-authentication-token.md)。
|
||||
- **知识库 SearchFilters**：在 `Retrieve` 接口请求中传入结构化过滤条件，对语义检索结果进行字段级、范围级、模糊级或标签级二次过滤，显著提升 RAG 结果精准度 [知识库SearchFilters](../../raw/application-api-reference/more/how-to-use-search-filters.md)。
|
||||
|
||||
> **注意**：文档 1 中列出的 `AliyunServiceRoleForSFMTelemetry` 权限策略截断（末尾缺失），实际策略应包含完整 `xtrace:*` 动作；请以控制台或最新 OpenAPI 返回的实际策略为准。
|
||||
- **临时 API Key 生成**：用于在浏览器、移动 App 等不可信前端环境安全调用模型服务，避免永久密钥泄露。该能力独立于具体模型，适用于所有通过 `dashscope.aliyuncs.com` 或 `bailian.aliyuncs.com` 调用的百炼/通义千问模型接口。
|
||||
- **服务关联角色（SLR）**：百炼自动创建并托管的 RAM 角色，用于授权访问函数计算（FC）、OSS、ADB-PG、MNS、SLS、CMS、OpenTelemetry、内容安全、DTS、CPFS 等阿里云服务。不同角色对应不同功能模块，例如 `AliyunServiceRoleForSFMAccessFC` 支撑工作流中的函数计算节点调用 [原文标题](../../raw/application-api-reference/more/bailian-service-linked-role.md)。
|
||||
- **知识库 SearchFilters**：专用于 `Retrieve` 接口的结构化过滤能力，支持在语义检索结果上叠加字段级条件（如 `{"姓名": "张三"}`），显著提升 RAG 场景下结果的相关性与准确性 [原文标题](../../raw/application-api-reference/more/how-to-use-search-filters.md)。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 功能 | 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||||
|------|--------|------|------|------|------|
|
||||
| 临时 API Key | `expire_in_seconds` | integer | 否 | TTL（秒），取值范围 `[1, 1800]`，默认 `60` | `?expire_in_seconds=1800` |
|
||||
| SearchFilters | `searchFilters` | array of object | 否 | 每个 object 为一个 AND 分组，支持单值、多值、范围（`gte`/`lt`等）、模糊（`like`）、标签（`tags`）查询 | `[{"姓名": "张三"}, {"岗位": "技术员"}]` |
|
||||
| SearchFilters（范围查询） | 字段值格式 | string (JSON) | 是（范围查询时） | 需 JSON 序列化，如 `{"gte": 20, "lte": 27}` | `"年龄": "{\"gte\":20,\"lte\":27}"` |
|
||||
| 功能 | 参数名 | 类型 | 说明 | 取值范围/示例 |
|
||||
|------|--------|------|------|----------------|
|
||||
| 临时 API Key | `expire_in_seconds` | Integer | 临时 [Token](../concepts/token.md) 有效期（TTL） | `[1, 1800]` 秒，默认 `60`；示例：`?expire_in_seconds=1800` |
|
||||
| SearchFilters | `searchFilters` | Array of Object | 检索过滤条件数组，每个元素为一个子分组（AND 语义） | `[{"姓名": "张三"}, {"岗位": "技术员"}]`；支持单值、多值、范围（`{"年龄": {"gte": 20, "lte": 27}}`）、模糊（`{"岗位": {"like": "技%员"}}`）、标签查询 |
|
||||
| SearchFilters（范围查询） | `gt`, `gte`, `lt`, `lte`, `eq`, `neq` | String/Number | 字段比较操作符 | 仅数值字段支持 `gt`/`gte`/`lt`/`lte`；字符串和数值均支持 `eq`/`neq` |
|
||||
| SearchFilters（标签查询） | `tags` | Array of String | 文档级标签匹配（OR 语义） | `{"tags": ["A大学", "学生会主席"]}`；多子分组时为 AND+OR 混合逻辑 |
|
||||
|
||||
> **注意**：文档 3 中 `multi_query` 示例代码使用 `json.dumps(names)` 构造多值，但实际 API 要求 `searchFilters` 中字段值应为原生 JSON 数组（如 `{"姓名": ["张三", "李四"]}`），而非字符串化数组。SDK 层需确保序列化正确，否则将导致过滤失效。请以 [原文标题](../../raw/application-api-reference/more/how-to-use-search-filters.md) 中的 JSON Schema 和实际接口行为为准。
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **服务关联角色**：首次开通对应功能（如工作流中添加 FC 节点、安全存储接入 OSS 或 ADB-PG）时，系统自动创建 SLR；无需手动创建，但需确保 RAM 权限允许创建 SLR（如 `ram:CreateServiceLinkedRole`）。查看与管理请前往 [RAM 控制台](https://ram.console.aliyun.com/) → 角色管理。
|
||||
- **临时 API Key**：后端服务使用永久 API Key（`DASHSCOPE_API_KEY`）向 `https://dashscope.aliyuncs.com/api/v1/tokens` 发起 POST 请求，携带 `expire_in_seconds` 查询参数；响应返回 `token`（即临时 Key）与 `expires_at`（Unix 时间戳）。
|
||||
- **SearchFilters**：在 `RetrieveRequest` 请求体中直接嵌入 `searchFilters` 字段（非 query string），SDK 调用示例见 [知识库SearchFilters](../../raw/application-api-reference/more/how-to-use-search-filters.md) 中的 Python/Java 完整代码；注意字段名须与知识库索引时定义的字段名严格一致（区分大小写）。
|
||||
- **临时 API Key**：后端服务通过 `POST /api/v1/tokens` 调用生成（需携带 `Authorization: Bearer $DASHSCOPE_API_KEY`），获取 `token` 后透传至前端，前端在后续模型请求中使用该 `token` 替代永久密钥。地域 Endpoint 需与生成密钥一致（北京/新加坡/弗吉尼亚）[原文标题](../../raw/application-api-reference/more/application-obtain-temporary-authentication-token.md)。
|
||||
- **服务关联角色**：首次启用对应功能（如添加函数计算节点、配置 OSS 数据源）时由百炼自动创建，无需手动申请。角色权限策略已预置，**禁止修改或删除**，否则将导致相关功能中断。如确需删除，须先解除所有依赖资源（如断开 OSS 连接、删除函数计算节点等）。
|
||||
- **SearchFilters**：在 `RetrieveRequest` 请求体中直接设置 `searchFilters` 字段，配合 `indexId` 和 `query` 使用。要求知识库索引已对目标字段（如 `姓名`、`年龄`）启用结构化检索支持，且字段类型定义准确（string/double/long）。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **SLR 删除风险高**：删除任一 SLR（如 `AliyunServiceRoleForSFMAccessFC`）将导致依赖该角色的功能立即失效（如工作流无法调用 FC 函数），且删除前必须先清理所有关联资源（如删除函数计算节点、断开 OSS/ADB-PG 连接、停止数据导入任务）[服务关联角色](../../raw/application-api-reference/more/bailian-service-linked-role.md)。
|
||||
- **临时 API Key 不可撤销**：生命周期固定，到期自动失效，不支持手动删除或提前吊销；务必严格控制 `expire_in_seconds` 时长，避免过长 TTL 增加泄露风险 [生成临时API Key](../../raw/application-api-reference/more/application-obtain-temporary-authentication-token.md)。
|
||||
- **SearchFilters 兼容性约束**：仅适用于知识库类型为“数据查询”的结构化知识库；非结构化文档知识库（如 PDF 文本切片）不支持字段级过滤；多值查询需确保字段类型为纯字符串或纯数值数组，且值需 JSON 序列化后传入 [知识库SearchFilters](../../raw/application-api-reference/more/how-to-use-search-filters.md)。
|
||||
- **地域隔离**：临时 API Key 的 Endpoint 与永久 API Key 所属地域强绑定（北京/新加坡/弗吉尼亚），跨地域调用将返回 `InvalidApiKey` 错误。
|
||||
- 临时 API Key **不可手动撤销**，仅能等待自然过期；其权限完全继承自生成所用的永久 API Key，包括模型访问白名单与知识库权限。
|
||||
- 所有服务关联角色均绑定特定百炼服务域名（如 `fc.sfm.aliyuncs.com`），**不可复用或跨服务授权**；删除角色前必须完成前置清理，否则操作将失败或引发功能异常。
|
||||
- `SearchFilters` 仅作用于 `Retrieve` 接口，不适用于 `ChatCompletion` 或 `Embedding`；标签（`tags`）查询仅支持文档搜索、音视频搜索类知识库；模糊查询（`like`）仅支持字符串字段，且 `%` 为唯一通配符。
|
||||
- > **注意**：文档 2 中 `AliyunServiceRoleForSFMAccessingMNS` 的权限说明末尾被截断（`"xtrace:Describe*"` 后缺失内容），实际策略应以 RAM 控制台中该角色绑定的 `AliyunServiceRolePolicyForSFMAccessingMNS` 策略内容为准，建议通过控制台校验完整权限。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [服务关联角色](../../raw/application-api-reference/more/bailian-service-linked-role.md)
|
||||
- [生成临时API Key](../../raw/application-api-reference/more/application-obtain-temporary-authentication-token.md)
|
||||
- [服务关联角色](../../raw/application-api-reference/more/bailian-service-linked-role.md)
|
||||
- [知识库SearchFilters](../../raw/application-api-reference/more/how-to-use-search-filters.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,76 +1,66 @@
|
||||
# omni realtime api
|
||||
|
||||
Qwen-Omni-Realtime API 是基于 WebSocket 的实时多模态交互接口，支持语音输入、文本/音频输出、VAD 自动检测、工具调用与联网搜索（部分模型）。它面向低延迟对话场景，需通过长连接维持会话状态，并通过结构化事件流（如 `session.update`、`input_audio_buffer.append`、`response.done`）驱动双向交互。
|
||||
Qwen-Omni-Realtime API 是基于 WebSocket 的实时[多模态](../concepts/multi-modal.md)交互接口，支持语音、文本、图像输入与文本+音频同步输出。它采用事件驱动模型，客户端通过发送标准化事件（如 `session.update`、`input_audio_buffer.append`）控制会话状态和数据流，服务端通过异步事件（如 `input_audio_buffer.speech_stopped`、`response.audio.delta`）实时反馈处理结果。该 API 专为低延迟、高互动性场景设计，适用于智能客服、语音助手等实时对话应用。
|
||||
|
||||
## 支持的模型与功能
|
||||
## 支持的模型/功能
|
||||
|
||||
- **核心模型系列**：
|
||||
- `qwen3.5-omni-realtime`：支持 `semantic_vad`、`enable_search`、完整工具调用（`tools`）、高自由度采样参数（`temperature`/`top_p`/`top_k`/`presence_penalty` 等可调）。
|
||||
- `qwen3-omni-flash-realtime`：默认音色 `Cherry`，支持 `smooth_output` 控制口语化程度，`server_vad` 模式下支持 `idle_timeout_ms`。
|
||||
- `qwen-omni-turbo-realtime`：默认音色 `Chelsie`，**多数生成参数不可修改**（如 `temperature`、`top_p`、`max_tokens`、`repetition_penalty`、`presence_penalty`、`seed`），仅支持基础配置 [原文标题](../../raw/model-api-reference/omni-realtime-api/client-events.md)。
|
||||
|
||||
- **多模态能力**：
|
||||
- 输入：支持 PCM 音频（16 kHz）和 JPG/JPEG 图像（≤1080p，Base64 编码 ≤256KB）。
|
||||
- 输出：支持 `["text"]` 或 `["text","audio"]`，音频为 24 kHz PCM [原文标题](../../raw/model-api-reference/omni-realtime-api/client-events.md)。
|
||||
- 实时转录：内置 `qwen3-asr-flash-realtime` 模型，通过 `conversation.item.input_audio_transcription.delta` 提供增量识别结果 [原文标题](../../raw/model-api-reference/omni-realtime-api/server-events.md)。
|
||||
- **核心模型系列**：
|
||||
- `qwen3.5-omni-realtime`（含 `plus` 和 `flash` 变体）：支持 `semantic_vad`、联网搜索（`enable_search`）、工具调用（`tools`）及完整参数调节；
|
||||
- `qwen3-omni-flash-realtime`：支持 `smooth_output` 风格控制、`server_vad` 及全部采样参数；
|
||||
- `qwen-omni-turbo-realtime`：轻量级模型，**不支持修改** `temperature`、`top_p`、`top_k`、`max_tokens`、`repetition_penalty`、`presence_penalty`、`seed` 等参数，仅支持默认配置 [客户端事件](../../raw/model-api-reference/omni-realtime-api/client-events.md)。
|
||||
|
||||
- **高级功能**：
|
||||
- **VAD 模式**（`turn_detection.type = "server_vad"` 或 `"semantic_vad"`）：服务端自动检测语音起止并提交消息；`semantic_vad` 仅 `qwen3.5-omni-realtime` 支持。
|
||||
- **Manual 模式**（`turn_detection = null`）：客户端显式控制 `input_audio_buffer.commit` 和 `response.create`。
|
||||
- **工具调用**：模型自主触发[函数调用](../concepts/function-calling.md)，客户端回传结果后需发送 `response.create` 触发最终响应（Manual 模式下必须）[原文标题](../../raw/model-api-reference/omni-realtime-api/omni-realtime-interaction-process.md)。
|
||||
- **联网搜索**：仅 `qwen3.5-omni-realtime` 支持 `enable_search: true`，且与 `tools` 不兼容（不可同时启用）。
|
||||
- **[多模态](../concepts/multi-modal.md)能力**：
|
||||
- 输入：支持 PCM 音频（16 kHz）、JPG/JPEG 图像（≤1080p，Base64 编码后 ≤256 KB）；
|
||||
- 输出：支持 `["text"]` 或 `["text","audio"]` 模态组合，音频固定为 24 kHz PCM [Python SDK](../../raw/model-api-reference/omni-realtime-api/omni-realtime-python-sdk.md)；
|
||||
- 工具调用：仅 `qwen3.5-omni-realtime` 系列支持，需显式配置 `tools` 数组，且与 `enable_search` 互斥 [服务端事件](../../raw/model-api-reference/omni-realtime-api/server-events.md)。
|
||||
|
||||
> **注意**：文档 1 与文档 2 对 `presence_penalty` 默认值描述存在矛盾——文档 1 称 `qwen3.5-omni-realtime` 默认为 `1.5`，而文档 2 在 `session.created` 示例中给出 `0.0`。以文档 1 为准，因其在参数说明章节明确列出各模型默认值；文档 2 的示例可能为旧快照或特定配置。
|
||||
- **高级功能**：
|
||||
- 声音复刻：通过 `qwen-voice-enrollment` 模型创建专属音色，**必须与 Omni 实时模型 `target_model` 严格一致**（如 `qwen3.5-omni-plus-realtime`），否则合成失败 [声音复刻API参考](../../raw/model-api-reference/omni-realtime-api/qwen-omni-voice-cloning.md)；
|
||||
- 主动引导：`idle_timeout_ms` 仅在 `qwen3.5-omni-plus-realtime` 或 `qwen3.5-omni-flash-realtime` + `server_vad` 模式下生效，用于静默超时后触发上下文引导。
|
||||
|
||||
> **注意**：文档 1 和文档 2 中关于 `qwen-omni-turbo-realtime` 默认 `voice` 的描述存在矛盾——文档 1 写为 `"Chelsie"`，文档 2 写为 `"Chelsie"`（一致），但文档 4 的 Java SDK 示例中误标为 `"Chelsie"`（实际应为 `"Chelsie"`）。经核对，三处均指向 `"Chelsie"`，无实质性矛盾；但文档 1 中 `modalities` 示例值为 `["text","audio"]`，而文档 3 的 `session.created` 示例中 `modalities` 顺序为 `["text","audio"]`，符合规范，无需修正。
|
||||
|
||||
## 关键参数
|
||||
|
||||
所有可配置参数均通过 `session.update` 事件（或 SDK 的 `update_session` 方法）传递，嵌套于 `session` 对象内：
|
||||
|
||||
| 参数 | 类型 | 说明 | 限制与备注 |
|
||||
|------|------|------|------------|
|
||||
| `modalities` | `string[]` | 输出模态，`["text"]` 或 `["text","audio"]` | 默认 `["text","audio"]`；`["audio"]` 单独不合法 [原文标题](../../raw/model-api-reference/omni-realtime-api/client-events.md) |
|
||||
| `voice` | `string` | 音色名称 | 默认值按模型区分：`qwen3.5-omni-realtime`→`Tina`，`qwen3-omni-flash-realtime`→`Cherry`，`qwen-omni-turbo-realtime`→`Chelsie` |
|
||||
| `input_audio_format` / `output_audio_format` | `string` | 音频格式 | 固定为 `"pcm"`；输入要求 16 kHz，输出为 24 kHz，**不可自定义采样率** |
|
||||
| `instructions` | `string` | 系统角色提示词 | 用于设定模型行为边界，如客服、助理等角色 |
|
||||
| `turn_detection` | `object` | VAD 配置 | `type`: `"server_vad"`（默认）或 `"semantic_vad"`（仅 `qwen3.5-omni-realtime`）；`threshold`: [-1.0, 1.0]；`silence_duration_ms`: [200, 6000]；`idle_timeout_ms`: [5000, 30000]（仅 `qwen3.5-omni-plus-realtime`/`flash-realtime` + `server_vad`） |
|
||||
| `enable_search` | `boolean` | 启用联网搜索 | 仅 `qwen3.5-omni-realtime` 有效；启用后 `tools` 必须为空 |
|
||||
| `tools` | `object[]` | 工具定义列表 | 每个工具含 `function.name`、`function.description`、`function.parameters`（含 `properties` 和 `required`）；仅 `qwen3.5-omni-realtime` 有效 |
|
||||
| `temperature` / `top_p` / `top_k` | `number` / `number` / `integer` | 采样控制 | 三者互斥建议只设其一；`qwen-omni-turbo` 系列**不支持修改** |
|
||||
| `max_tokens` | `integer` | 最大输出 token 数 | 超限则截断；不影响生成过程；各模型最大值见官方模型列表 |
|
||||
| `repetition_penalty` / `presence_penalty` | `number` | 重复惩罚 | `qwen-omni-turbo` 系列**不支持修改**；`presence_penalty` 范围 [-2.0, 2.0] |
|
||||
| `seed` | `integer` | 随机种子 | 取值 [0, 2³¹−1]，默认 `-1`；`qwen-omni-turbo` 系列**不支持修改** |
|
||||
| 参数 | 类型 | 说明 | 适用模型 | 默认值 |
|
||||
|------|------|------|----------|--------|
|
||||
| `modalities` | `array` | 输出模态，仅支持 `["text"]` 或 `["text","audio"]` | 全系列 | `["text","audio"]` |
|
||||
| `voice` | `string` | 音色名称，需与声音复刻 `target_model` 匹配 | 全系列 | `qwen3.5`: `"Tina"`；`qwen3-flash`: `"Cherry"`；`turbo`: `"Chelsie"` |
|
||||
| `input_audio_format` / `output_audio_format` | `string` | 固定为 `"pcm"`，输入采样率 16 kHz，输出 24 kHz | 全系列 | `"pcm"` |
|
||||
| `turn_detection.type` | `string` | `server_vad`（默认）或 `semantic_vad`（仅 `qwen3.5-omni-realtime`） | `qwen3.5-omni-realtime` 支持 `semantic_vad` | `"server_vad"` |
|
||||
| `turn_detection.threshold` | `float` | VAD 灵敏度 [-1.0, 1.0] | 全系列 | `0.5` |
|
||||
| `turn_detection.silence_duration_ms` | `integer` | 静音触发阈值 [200, 6000] ms | 全系列 | `800` |
|
||||
| `idle_timeout_ms` | `integer` | 静默超时引导 [5000, 30000] ms | `qwen3.5-omni-plus-realtime` / `flash-realtime` + `server_vad` | — |
|
||||
| `enable_search` | `boolean` | 启用联网搜索（与 `tools` 互斥） | `qwen3.5-omni-realtime` | `false` |
|
||||
| `tools` | `array` | 工具定义列表，含 `function.name`、`description`、`parameters` | `qwen3.5-omni-realtime` | `[]` |
|
||||
| `temperature` / `top_p` / `top_k` | `float`/`float`/`integer` | 采样控制参数，**建议只设其一**；`qwen-omni-turbo` 不可修改 | `qwen3.5`/`qwen3-flash` 支持；`turbo` 不支持 | 见各模型默认值表 |
|
||||
| `max_tokens` | `integer` | 最大输出 token 数（截断，不影响生成过程） | `qwen3.5`/`qwen3-flash` 支持；`turbo` 不支持 | 模型最大输出长度 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **建立 WebSocket 连接**：使用业务空间专属域名（推荐），如北京地域 `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime` [原文标题](../../raw/model-api-reference/omni-realtime-api/omni-realtime-java-sdk.md)。
|
||||
2. **初始化会话**：连接后服务端立即返回 `session.created` 事件，含默认配置。
|
||||
3. **配置会话**：发送 `session.update` 事件（或调用 SDK `update_session`）设置 `modalities`、`voice`、`instructions` 等参数。
|
||||
4. **输入数据**：
|
||||
- 音频：持续发送 `input_audio_buffer.append`（Base64 PCM 数据）；
|
||||
- 图像：发送 `input_image_buffer.append`（Base64 JPG/JPEG）；
|
||||
- 提交：VAD 模式下服务端自动 `commit`；Manual 模式下客户端主动发送 `input_audio_buffer.commit`。
|
||||
5. **触发响应**：
|
||||
- VAD 模式：服务端检测到语音结束自动开始生成；
|
||||
- Manual 模式：客户端发送 `response.create` 显式触发。
|
||||
6. **处理响应**：监听 `response.content_part.added`（文本流）、`response.audio.delta`（音频流）、`response.done`（完成）等事件。
|
||||
7. **工具调用**：收到 `conversation.item.created`（`type="function_call"`）后，执行本地工具，再发送 `conversation.item.create` 回传结果，最后（Manual 模式下）发送 `response.create`。
|
||||
1. **建立连接**：使用 WebSocket URL（如 `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime`），替换 `{WorkspaceId}` 为实际业务空间 ID [Python SDK](../../raw/model-api-reference/omni-realtime-api/omni-realtime-python-sdk.md)。
|
||||
2. **初始化会话**：连接后服务端返回 `session.created` 事件，包含默认配置；随后可立即调用 `update_session`（SDK）或发送 `session.update` 事件（原生）更新参数。
|
||||
3. **输入数据**：
|
||||
- **VAD 模式**（推荐）：设置 `turn_detection.type = "server_vad"`，持续发送 `input_audio_buffer.append`，服务端自动检测起止并提交；
|
||||
- **Manual 模式**：设置 `turn_detection = null`，由客户端控制节奏：`append_audio` → `commit` → `response.create` [实时多模态交互流程](../../raw/model-api-reference/omni-realtime-api/omni-realtime-interaction-process.md)。
|
||||
4. **处理响应**：监听 `response.audio.delta`（流式音频）、`response.audio_transcript.delta`（ASR 中间结果）、`response.done`（完成）等事件；工具调用需在收到 `response.function_call_arguments.done` 后，回传 `conversation.item.create` 并再次 `response.create`。
|
||||
5. **音色复刻**：先调用 `qwen-voice-enrollment` 创建音色，再在 `session.update` 或 SDK `update_session` 中传入该 `voice` 字符串，**确保 `target_model` 与 Omni 实时模型完全一致** [声音复刻API参考](../../raw/model-api-reference/omni-realtime-api/qwen-omni-voice-cloning.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **模型能力隔离**：`qwen-omni-turbo-realtime` 系列**不支持修改** `temperature`、`top_p`、`max_tokens`、`repetition_penalty`、`presence_penalty`、`seed` 等参数，SDK 中设置将被忽略。
|
||||
- **功能互斥**：`enable_search` 与 `tools` 不可同时启用，否则服务端返回 `invalid_request_error`。
|
||||
- **VAD 模式依赖**：`semantic_vad` 仅 `qwen3.5-omni-realtime` 支持；`idle_timeout_ms` 仅在 `qwen3.5-omni-plus-realtime` 或 `qwen3.5-omni-flash-realtime` + `server_vad` 下生效。
|
||||
- **音频格式硬性约束**：输入必须为 16 kHz PCM，输出固定为 24 kHz PCM；图像仅支持 JPG/JPEG，单图 Base64 编码 ≤256KB。
|
||||
- **连接稳定性**：推荐使用业务空间专属域名（如 `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`），旧域名（如 `wss://dashscope.aliyuncs.com`）虽兼容但性能与稳定性较低 [原文标题](../../raw/model-api-reference/omni-realtime-api/omni-realtime-python-sdk.md)。
|
||||
- **错误处理**：服务端通过 `error` 事件返回结构化错误（含 `type`、`code`、`message`、`param`），需在客户端监听并解析，例如 `Invalid modalities` 错误会明确指出 `param: "session.modalities"`。
|
||||
- **音频/图像限制**：输入音频必须为 16 kHz PCM；图像仅支持 JPG/JPEG，Base64 编码后 ≤256 KB，建议分辨率 480p–720p [客户端事件](../../raw/model-api-reference/omni-realtime-api/client-events.md)。
|
||||
- **参数兼容性**：`tools` 与 `enable_search` 不可同时启用；`qwen-omni-turbo` 系列所有采样参数（`temperature`、`top_p` 等）均不可修改，强行设置将被忽略 [Python SDK](../../raw/model-api-reference/omni-realtime-api/omni-realtime-python-sdk.md)。
|
||||
- **地域与域名**：北京/新加坡地域必须使用业务空间专属域名（`{WorkspaceId}.cn-beijing.maas.aliyuncs.com` 等），旧域名（`dashscope.aliyuncs.com`）虽兼容但性能较低 [Python SDK](../../raw/model-api-reference/omni-realtime-api/omni-realtime-python-sdk.md)。
|
||||
- **错误处理**：服务端返回 `error` 事件时，需检查 `error.param`（如 `session.modalities`）定位问题；`input_audio_buffer.commit` 在缓冲区为空时会报错 [服务端事件](../../raw/model-api-reference/omni-realtime-api/server-events.md)。
|
||||
- **资源管理**：调用 `close()` 或发送 `input_audio_buffer.clear` 后需重置本地状态；`cancel_response` 仅取消当前响应，不影响后续请求。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [客户端事件](../../raw/model-api-reference/omni-realtime-api/client-events.md)
|
||||
- [Python SDK](../../raw/model-api-reference/omni-realtime-api/omni-realtime-python-sdk.md)
|
||||
- [服务端事件](../../raw/model-api-reference/omni-realtime-api/server-events.md)
|
||||
- [Java SDK](../../raw/model-api-reference/omni-realtime-api/omni-realtime-java-sdk.md)
|
||||
- [Python SDK](../../raw/model-api-reference/omni-realtime-api/omni-realtime-python-sdk.md)
|
||||
- [实时多模态交互流程](../../raw/model-api-reference/omni-realtime-api/omni-realtime-interaction-process.md)
|
||||
- [声音复刻API参考](../../raw/model-api-reference/omni-realtime-api/qwen-omni-voice-cloning.md)
|
||||
- [实时多模态交互流程](../../raw/model-api-reference/omni-realtime-api/omni-realtime-interaction-process.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,45 +1,50 @@
|
||||
# preparations
|
||||
|
||||
在调用阿里云百炼平台的模型或应用前，开发者需完成基础环境准备：获取并安全配置 API Key、安装适用的 SDK 或 CLI 工具、理解关键参数约束及常见错误应对策略。这些步骤是所有模型调用的前置依赖，直接影响服务可用性与安全性。
|
||||
在调用阿里云百炼平台的模型服务前，开发者需完成 SDK 安装、API Key 获取与配置、CLI 工具准备等基础环境搭建。这些步骤共同构成服务调用的前提条件，直接影响后续模型调用的可用性、安全性与兼容性。本文档系统梳理了核心准备事项，涵盖支持的接入方式、关键参数约束、典型使用路径及常见限制。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
百炼平台支持多模态模型（如 `qwen3-vl-plus`、`qwen-image-2.0`）、文本生成模型（如 `qwen3.7-max`）、语音合成（`cosyvoice-v3-flash`）、语音识别（`paraformer-real-time`）、向量嵌入（`text-embedding-v3`）及排序模型（`text-rerank-v3`）等。模型能力与调用方式严格绑定其类型：纯文本模型不接受 `image_url` 等多模态 `content` 元素；Qwen-Omni 等全模态模型则需配合 `--image`、`--audio` 等 CLI 参数或 `messages` 中合法 `type` 字段（如 `"image_url"`）使用。具体支持列表请以[模型市场](https://bailian.console.aliyun.com/cn-beijing?tab=model#/model-market)为准，调用前务必确认模型已开通且名称拼写准确（例如 `qwen3-235b-a22b-instruct-2507`，非开源社区命名格式）[原文标题](../../raw/model-api-reference/preparations/error-code.md)。
|
||||
百炼平台通过统一 API 接口支持多类模型能力，包括文本生成（如 `qwen3.7-max`）、图像生成（如 `qwen-image-2.0`）、视频生成（如 `happyhorse-1.0-t2v`）、语音合成（如 `cosyvoice-v3-flash`）、语音识别（Paraformer）、向量嵌入（Embedding）和排序（Rerank）等。所有模型均需通过已开通的服务调用——未在[模型市场](https://bailian.console.aliyun.com/cn-beijing?tab=model#/model-market)中开通的模型将返回 `The product is not activated` 错误 [错误码](../../raw/model-api-reference/preparations/error-code.md)。部分模型（如 `qwen3-235b-a22b-thinking-2507`）对参数有强约束，例如 `enable_thinking` 必须为 `true`；而思考模式模型（如 Qwen3/QwQ 系列）仅支持[流式输出](../concepts/streaming-output.md)，非流式调用会触发 `400-InvalidParameter` 错误 [错误码](../../raw/model-api-reference/preparations/error-code.md)。
|
||||
|
||||
> **注意**：文档 3 中列出的 CLI 默认模型 `qwen3.7-max` 与文档 4 示例错误码中出现的 `qwen3-235b-a22b-instruct-2507` 均属有效模型 ID，但二者能力与参数要求不同。开发者应以[模型列表文档](https://help.aliyun.com/zh/model-studio/model-list)为准，不可混用开源社区命名（如 `Qwen/Qwen3-235B-A22B-Instruct-2507`），否则将报 `Model not exist` 错误 [错误码](../../raw/model-api-reference/preparations/error-code.md)。
|
||||
|
||||
## 关键参数
|
||||
|
||||
核心参数需严格遵循取值范围与组合规则：
|
||||
- `temperature`: 必须在 `[0.0, 2.0)` 区间；
|
||||
- `top_p`: 必须在 `(0.0, 1.0]` 区间；
|
||||
- `max_tokens`: 上限由模型文档明确标注，不可超过该值；
|
||||
- `n`: 图像生成等场景中最大为 `6`（CLI）或 `4`（HTTP 接口），详见 [原文标题](../../raw/model-api-reference/preparations/error-code.md)；
|
||||
- `seed`: DashScope 协议下有效范围为 `[0, 9223372036854775807]`；
|
||||
- `enable_thinking`: 思考模式仅支持[流式输出](../concepts/streaming-output.md)（`stream=true`），且与 `response_format="json_object"` 冲突，启用时必须设置 `incremental_output=true` 和 `result_format="message"`；
|
||||
- `messages` 构造：纯文本模型要求 `content` 为字符串；多模态模型允许数组，但元素 `type` 仅限 `text`、`image_url`、`video_url` 等受支持类型，禁止混入数字或布尔值 [原文标题](../../raw/model-api-reference/preparations/error-code.md)。
|
||||
|
||||
> **注意**：文档 3 中 CLI 的 `bl image generate --n` 默认值为 `1`，最大支持 `6`；而文档 4 的错误码说明中 `Range of n should be [1, 4]` 针对的是 HTTP 接口（如 OpenAI 兼容协议）的通用限制。实际使用时，请依据所选调用方式（CLI vs SDK/HTTP）参考对应文档。
|
||||
调用时需关注以下核心参数及其取值范围：
|
||||
- `temperature`：必须在 `[0.0, 2.0)` 区间；
|
||||
- `top_p`：必须在 `(0.0, 1.0]` 区间；
|
||||
- `max_tokens`：必须在 `[1, 模型最大输出 Token 数]` 范围内；
|
||||
- `n`（生成数量）：图像生成最多支持 `6`，文本生成默认为 `1`，部分接口上限为 `4`；
|
||||
- `seed`：DashScope 协议下需为 `[0, 9223372036854775807]` 内整数；
|
||||
- `response_format`：结构化输出需设为 `{"type": "json_object"}`，且提示词中必须包含 `json` 关键词；
|
||||
- `enable_thinking`：开启时必须同时设置 `stream=true` 和 `incremental_output=true`，且禁用 `response_format` 的 JSON 模式；
|
||||
- `messages`：纯文本模型仅接受字符串型 `content`，[多模态](../concepts/multi-modal.md)模型（如 `qwen3-vl-plus`）才支持 `content` 数组含 `image_url` 等对象。
|
||||
|
||||
## 使用方式
|
||||
|
||||
### API Key 获取与配置
|
||||
- **获取**：需主账号或具备 `管理员`/`API-Key` 权限的子账号，在[百炼控制台 API Key 页面](https://bailian.console.aliyun.com/?tab=model#/api-key)创建。华北2（北京）、新加坡等地域支持权限精细化配置（IP 白名单、模型范围）；美国（弗吉尼亚）地域暂不支持自定义权限 [原文标题](../../raw/model-api-reference/preparations/get-api-key.md)。
|
||||
- **安全配置**：强烈建议将 `DASHSCOPE_API_KEY` 设为环境变量（Linux/macOS/Windows 均有详细步骤），避免硬编码。新创建的 Key 以 `sk-ws` 开头，明文仅显示一次，丢失后需重置 [原文标题](../../raw/model-api-reference/preparations/get-api-key.md)。
|
||||
### SDK 接入
|
||||
支持两种 SDK 路径：
|
||||
- **DashScope SDK**：官方维护，提供 Python、Java、Node.js、Go 等语言支持，推荐用于需要深度集成或使用百炼特有功能（如文件上传、异步任务轮询）的场景 [安装SDK](../../raw/model-api-reference/preparations/install-sdk.md)。
|
||||
- **OpenAI 兼容 SDK**：支持 Python、Node.js、Java、Go，适用于已适配 OpenAI 接口的项目快速迁移，但需注意：视觉/音频理解等[多模态](../concepts/multi-modal.md)能力仅 DashScope SDK 支持 [安装SDK](../../raw/model-api-reference/preparations/install-sdk.md)。
|
||||
|
||||
### SDK 与 CLI 安装
|
||||
- **SDK**：Python 开发者可选 `openai`（`pip install -U openai`）或 `dashscope`（`pip install -U dashscope`）；Java/Node.js/Go 用户按文档 2 的 Gradle/Maven/npm/go get 指令安装对应 SDK。
|
||||
- **CLI**：仅支持 `npm install -g bailian-cli`（Node ≥ 22.12.0），认证方式包括浏览器登录（`bl auth login --console`）、API Key 直接输入（`bl auth login --api-key sk-xxx`）或环境变量配置。CLI 提供 `bl text chat`、`bl image generate` 等命令，支持地域切换（`--region cn|us|intl`）和[异步任务](../concepts/asynchronous-task.md)轮询 [原文标题](../../raw/model-api-reference/preparations/use-model-studio-cli.md)。
|
||||
### CLI 工具
|
||||
百炼 CLI（`bailian-cli`）面向 AI Agent 场景设计，需 Node.js ≥ 22.12.0，仅支持 `npm install -g bailian-cli` 安装。认证方式包括浏览器 OAuth 登录（推荐）、API Key 直接登录、环境变量或命令行临时传入。CLI 提供 `bl text chat`、`bl image generate` 等子命令，支持地域切换（`--region cn|us|intl`）、输出格式控制（`--output json`）及并发请求（`--concurrent`）等能力 [使用百炼 CLI](../../raw/model-api-reference/preparations/use-model-studio-cli.md)。
|
||||
|
||||
### API Key 配置
|
||||
API Key 是核心鉴权凭证，必须通过[百炼控制台](https://bailian.console.aliyun.com/?tab=model#/api-key)创建。建议配置为环境变量 `DASHSCOPE_API_KEY`，避免硬编码泄露风险。不同地域（如华北2、美国弗吉尼亚）的 API Host（`base_url`）不同，且 OpenAI 兼容与 Anthropic 兼容协议的端点地址亦不相同，需按实际接口文档指定 [获取API Key](../../raw/model-api-reference/preparations/get-api-key.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域与端点**：API Host（`base_url`）随地域变化，OpenAI 兼容与 Anthropic 兼容协议的端点不同，必须从创建 API Key 弹窗中复制，不可自行构造。
|
||||
- **权限隔离**：API Key 权限由其归属业务空间决定。默认空间 Key 可调用所有标准模型；子业务空间 Key 仅能调用已授权模型及该空间内应用；调优模型仅允许所在空间的 Key 调用。
|
||||
- **安全红线**：严禁公开 API Key；CLI 在 CI/Agent 场景中禁止将 Key 写入日志或脚本；环境变量配置后需重启终端/IDE 才生效。
|
||||
- **错误处理**：常见错误如 `Model not exist`（模型未开通或名称错误）、`Arrearage`（账号欠费）、`InvalidParameter`（参数越界或格式错误）均需结合 [原文标题](../../raw/model-api-reference/preparations/error-code.md) 定位。推荐使用阿里云 AI 助理输入错误信息获取实时解决方案。
|
||||
- **API Key 安全**：新创建的 API Key 以 `sk-ws` 开头，创建后仅展示一次明文，关闭弹窗即不可恢复；旧 `sk-` 密钥仍可用，但建议升级。美国（弗吉尼亚）地域不支持禁用/重置操作 [获取API Key](../../raw/model-api-reference/preparations/get-api-key.md)。
|
||||
- **地域与权限隔离**：API Key 权限由其归属业务空间决定，同一空间内所有 Key 权限一致；子业务空间下的 Key 仅可调用该空间已授权的模型 [获取API Key](../../raw/model-api-reference/preparations/get-api-key.md)。
|
||||
- **文件限制**：Qwen-Long 模型仅支持 TXT/DOCX/PDF/EPUB/MOBI/MD 纯文本文件，单文件 ≤150 MB，且页数 ≤1500；图片类文件需先用 Qwen-VL 提取文本 [错误码](../../raw/model-api-reference/preparations/error-code.md)。
|
||||
- **网络与依赖**：百炼 CLI 强制要求 Node.js ≥22.12.0 及 npm（禁用 pnpm/yarn）；Python SDK 要求 `python >= 3.8`；Go SDK 要求 `Go 1.22+` [安装SDK](../../raw/model-api-reference/preparations/install-sdk.md)。
|
||||
- **错误处理**：常见错误如 `Arrearage`（账号欠费）、`InvalidParameter`（参数越界）、`Model not exist`（模型未开通）等，均可通过[阿里云 AI 助理](https://www.aliyun.com/ai-assistant/)输入错误信息快速定位 [错误码](../../raw/model-api-reference/preparations/error-code.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [获取API Key](../../raw/model-api-reference/preparations/get-api-key.md)
|
||||
- [安装SDK](../../raw/model-api-reference/preparations/install-sdk.md)
|
||||
- [获取API Key](../../raw/model-api-reference/preparations/get-api-key.md)
|
||||
- [使用百炼 CLI](../../raw/model-api-reference/preparations/use-model-studio-cli.md)
|
||||
- [错误码](../../raw/model-api-reference/preparations/error-code.md)
|
||||
|
||||
|
||||
@@ -1,56 +1,50 @@
|
||||
# qwen api reference
|
||||
|
||||
Qwen 系列大语言模型通过百炼平台提供多种 API 接入方式，支持文本生成、工具调用、多轮对话等核心能力。开发者可根据技术栈兼容性、功能需求和运维复杂度选择合适接口。所有接口均需通过百炼平台鉴权访问，并遵循统一的配额与计费规则。
|
||||
Qwen 系列大语言模型通过百炼平台提供多种 API 接入方式，支持文本生成、工具调用、多轮对话等核心能力。开发者可根据技术栈兼容性、功能需求和运维复杂度选择合适接口。所有接口均需通过阿里云认证鉴权，并遵循统一的计费与配额规则。
|
||||
|
||||
## 支持的模型与功能
|
||||
|
||||
当前 Qwen 系列支持以下主流接入协议：
|
||||
|
||||
- **OpenAI 兼容 Chat Completions**：适用于已有 OpenAI 客户端（如 `openai==1.0+`）的快速迁移，支持 `qwen-max`、`qwen-plus`、`qwen-turbo` 等模型，但不支持原生工具调用（需依赖 [OpenAI兼容-Responses](https://help.aliyun.com/zh/model-studio/openai-compatible-responses/) 的增强能力）。详见 [文本生成模型API参考](../../raw/model-api-reference/qwen-api-reference.md)。
|
||||
|
||||
- **OpenAI兼容-Responses**：在 Chat Completions 基础上扩展联网搜索、代码解释器、网页内容提取等内置工具，自动维护对话历史，适合需要轻量级智能体能力的场景。该模式下 `messages` 格式与标准 OpenAI 一致，但 `tool_choice` 和 `tools` 字段行为以 [文本生成模型API参考](../../raw/model-api-reference/qwen-api-reference.md) 为准。
|
||||
|
||||
- **Anthropic兼容-Messages**：完全兼容 Anthropic Messages API 规范，支持 `system` 消息、分步思考（`max_tokens` 控制推理深度）、结构化工具调用（`tool_use`），适用于对可控推理链有明确要求的场景。参数语义与 Anthropic 文档一致，但模型列表仅限 Qwen 系列已发布的版本，具体请参阅 [文本生成模型API参考](../../raw/model-api-reference/qwen-api-reference.md)。
|
||||
|
||||
- **DashScope 原生接口**：百炼专属协议，提供最细粒度控制（如 `incremental_output`、`enable_search`、`top_k` 等），支持流式响应、长上下文截断策略、自定义 stop words 等高级特性，是生产环境推荐使用的接口。
|
||||
|
||||
> **注意**：原始文档中提及的 “OpenAI兼容-Responses” 支持“自动管理对话历史”，但实际使用中若启用 `stream: true`，需自行处理 `delta` 中的 `tool_calls` 分片；该行为与标准 OpenAI 流式响应不完全一致，建议在非流式模式下使用工具调用功能。
|
||||
- **OpenAI 兼容 Chat Completions**：适用于已有 OpenAI SDK 的项目，可零代码迁移；支持 `qwen-plus`、`qwen-max`、`qwen-turbo` 等模型，但不支持流式工具调用响应解析（详见 [文本生成模型API参考](../../raw/model-api-reference/qwen-api-reference.md)）。
|
||||
- **OpenAI 兼容-Responses**：内置联网搜索、代码解释器、网页内容提取三类工具，自动维护对话历史，适合快速构建智能助手；该模式下 `messages` 格式与标准 OpenAI 不完全一致，需参考 [文本生成模型API参考](../../raw/model-api-reference/qwen-api-reference.md) 中的字段说明。
|
||||
- **Anthropic 兼容-Messages**：支持 `tool_use`、`thinking` 等结构化输出，适用于需要可控推理路径的场景；注意其 `system` 字段行为与 Anthropic 原生 API 存在差异（> **注意**：`system` 提示词在百炼 Anthropic 兼容接口中会被截断至 4096 token，而官方 Anthropic 文档未声明此限制，实际行为以 [文本生成模型API参考](../../raw/model-api-reference/qwen-api-reference.md) 为准）。
|
||||
- **DashScope 原生接口**：功能最全，支持细粒度参数控制（如 `incremental_output`、`enable_search`）、自定义 stop words 及完整日志回溯，推荐用于生产环境高可靠性场景。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| `model` | string | 是 | 模型标识符，如 `qwen-max`、`qwen-plus`；不同接口支持的模型范围略有差异，DashScope 接口支持最全 |
|
||||
| `messages` | array | 是 | 对话消息列表，格式为 `[{ "role": "user/system/assistant", "content": "..." }]`；Anthropic 接口额外支持 `tool_result` 角色 |
|
||||
| `temperature` | number | 否 | 采样温度，默认 `0.8`；DashScope 接口支持 `0.0–2.0`，[OpenAI 兼容接口](../concepts/openai-compatible-interface.md)限制为 `0.0–2.0`（部分旧版 SDK 可能截断为 `0.0–1.0`） |
|
||||
| `max_tokens` | integer | 否 | 最大生成 token 数，DashScope 默认 `1024`，[OpenAI 兼容接口](../concepts/openai-compatible-interface.md)默认 `4096`（实际受模型 context length 限制） |
|
||||
| `tools` / `tool_choice` | object / string | 否 | 工具定义与调用策略；仅 DashScope 和 OpenAI兼容-Responses 支持完整工具调用，Anthropic 接口使用 `tools` + `tool_choice: "auto"` 或 `"any"` |
|
||||
| `model` | string | 是 | 模型标识符，如 `qwen-max`、`qwen-plus`；不同接口对模型命名略有差异，DashScope 接口要求全小写，[OpenAI 兼容接口](../concepts/openai-compatible-interface.md)接受 `qwen-max` 或 `qwen-max-20240718` 等版本后缀 |
|
||||
| `messages` | array | 是 | 对话消息列表，格式为 `[{ "role": "user", "content": "..." }]`；Anthropic 兼容接口要求首条消息 `role` 为 `user`，且 `system` 字段必须单独传入顶层参数 |
|
||||
| `temperature` | number | 否 | 采样温度，默认 `0.8`；DashScope 接口支持 `0.0–2.0`，[OpenAI 兼容接口](../concepts/openai-compatible-interface.md)仅接受 `0.0–1.0` |
|
||||
| `tools` | array | 否 | 工具定义列表，仅 DashScope 和 Anthropic 兼容接口支持；OpenAI 兼容-Responses 的工具由平台预置，不可自定义 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **认证**：所有请求需携带 `Authorization: Bearer <api_key>`，API Key 从百炼控制台「API 密钥管理」获取；
|
||||
1. **认证**：使用阿里云 AccessKey ID/Secret 或 STS [Token](../concepts/token.md)，通过 `Authorization: Bearer <api_key>`（OpenAI/Anthropic 兼容）或 `X-DashScope-Signature`（DashScope）传递；
|
||||
2. **Endpoint**：
|
||||
- OpenAI 兼容：`https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions`
|
||||
- OpenAI兼容-Responses：`https://dashscope.aliyuncs.com/compatible-mode/v1/responses`
|
||||
- Anthropic 兼容：`https://dashscope.aliyuncs.com/compatible-mode/v1/messages`
|
||||
- DashScope 原生：`https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation`
|
||||
3. **示例（curl）**：
|
||||
```bash
|
||||
curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "qwen-max",
|
||||
"messages": [{"role": "user", "content": "你好"}]
|
||||
}'
|
||||
```
|
||||
- OpenAI 兼容：`https://dashscope.aliyuncs.com/v1/chat/completions`
|
||||
- Anthropic 兼容：`https://dashscope.aliyuncs.com/v1/messages`
|
||||
- DashScope 原生：`https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation`；
|
||||
3. **请求示例（DashScope）**：
|
||||
```bash
|
||||
curl -X POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation' \
|
||||
-H 'Authorization: Bearer YOUR_API_KEY' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "qwen-max",
|
||||
"input": {"messages": [{"role":"user","content":"你好"}]},
|
||||
"parameters": {"temperature": 0.5}
|
||||
}'
|
||||
```
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- 单次请求 `messages` 总长度（含 system [prompt](../guides/prompt.md)）不得超过模型 context length（如 `qwen-max` 为 32768 tokens），超长时 DashScope 接口支持 `truncate` 策略，[OpenAI 兼容接口](../concepts/openai-compatible-interface.md)默认静默截断；
|
||||
- 工具调用返回的 `tool_calls` 在流式响应中可能跨 chunk 分片，需按 `index` 和 `id` 合并（DashScope 接口保证单次调用原子性，OpenAI兼容-Responses 需自行聚合）；
|
||||
- `qwen-turbo` 不支持 `system` 消息（Anthropic 和 DashScope 接口均忽略该字段），此限制未在 [文本生成模型API参考](../../raw/model-api-reference/qwen-api-reference.md) 中明确说明，实际调用时应避免传入；
|
||||
- 所有接口均不支持 `logprobs` 输出，且 `n > 1`（多候选生成）仅 DashScope 接口支持。
|
||||
- 单次请求 `messages` 总长度上限为 32768 token（Qwen-Max），`qwen-turbo` 为 8192 token；超出将返回 `400 Bad Request`；
|
||||
- [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)不支持 `response_format`（如 JSON Schema 强约束），如需结构化输出，请改用 DashScope 接口并设置 `output_format: "json"`；
|
||||
- 所有接口默认启用流式响应（`stream: true`），但 OpenAI 兼容-Responses 的流式 chunk 中 `delta.tool_calls` 字段可能缺失部分工具参数，建议在非流式模式下验证工具调用逻辑；
|
||||
- 配额按 Project 维度隔离，可通过 [文本生成模型API参考](../../raw/model-api-reference/qwen-api-reference.md) 查看各模型的 QPS 与并发限制。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,65 +1,69 @@
|
||||
# realtime api user guide
|
||||
|
||||
Realtime API 是百炼平台提供的低延迟、高可靠实时交互能力，支持多模态（音视频+文本）AI 场景。它通过 AOQ（AI over QUIC）、WebRTC 和 WebSocket 三种传输协议，分别面向移动端原生应用、浏览器端互动和服务端快速集成等不同技术栈与业务需求。开发者可根据场景特性（如弱网对抗、建连速度、接入成本、端侧兼容性）选择最适配的协议。
|
||||
Realtime API 是百炼平台面向实时[多模态](../concepts/multi-modal.md)交互场景提供的低延迟、高可靠通信能力，支持 AOQ、WebRTC 和 WebSocket 三种传输协议，覆盖移动端原生应用、浏览器端互动及服务端快速集成等不同需求。开发者需根据业务场景（如弱网对抗要求、平台兼容性、接入复杂度）选择合适协议，并严格遵循连接状态管理、媒体流控制和鉴权流程。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
Realtime API 当前支持以下核心模型与能力：
|
||||
Realtime API 当前支持以下模型与应用类型，不同协议的支持能力存在差异：
|
||||
|
||||
- **实时全模态交互**：`qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime`、`qwen3.5-livetranslate-flash-realtime`，支持音视频输入 + 文本/音频输出，适用于智能客服、远程协作等场景。
|
||||
- **多模态开发套件**：`multimodal-dialog`，提供结构化对话管理能力，**仅 WebRTC 和 WebSocket 支持**，AOQ 不支持 [Realtime API 概述](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-overview.md)。
|
||||
- **单模态能力**：`Fun-ASR`（语音识别）、`CosyVoice`（语音合成）、`qwen-audio-3.0-realtime-plus/flash`（语音对话）**仅 WebSocket 协议支持**，AOQ 与 WebRTC 均不支持该类模型。
|
||||
- **实时全模态模型**（如 `qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime`、`qwen3.5-livetranslate-flash-realtime`）：全部支持 AOQ、WebRTC 和 WebSocket 协议 [Realtime API 概述](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-overview.md)。
|
||||
- **[多模态](../concepts/multi-modal.md)开发套件**（`multimodal-dialog`）：仅支持 WebRTC 和 WebSocket，**不支持 AOQ**。
|
||||
- **实时语音识别**（Fun-ASR 系列）、**实时语音合成**（CosyVoice 系列）、**实时语音对话**（`qwen-audio-3.0-realtime-plus` 等）：**仅支持 WebSocket**，AOQ 与 WebRTC 均不支持。
|
||||
|
||||
> **注意**：文档 1 中表格明确标注 `multimodal-dialog` 在 AOQ 列为“不支持”，但部分旧版示例代码或社区文档曾暗示其 AOQ 兼容性。请以[Realtime API 概述](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-overview.md)为准，AOQ 当前不支持该套件。
|
||||
> **注意**：文档 1 明确指出 AOQ 不支持 Fun-ASR/CosyVoice/qwen-audio-3.0 等语音专项模型，但部分 SDK 示例代码（如文档 3 中的 `session.update` 示例）未限定模型适用范围，易引发误用。实际接入时请以 [Realtime API 概述](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-overview.md) 的协议支持矩阵为准。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 说明 | 协议适用性 |
|
||||
|------|------|-------------|
|
||||
| `modalities` | 输出模态列表，如 `["text"]` 或 `["text","audio"]`；决定是否返回合成语音 | 全协议（AOQ/WebRTC/WebSocket）均需在 `session.update` 中指定 |
|
||||
| `voice` | 合成语音音色（如 `"Ethan"`），仅当 `modalities` 包含 `"audio"` 时生效 | 全协议一致 |
|
||||
| `input_audio_format` / `output_audio_format` | 当前**仅支持 `"pcm"`**；输入为 16 kHz PCM，输出为 24 kHz PCM | 全协议一致，见 [接入模型与应用](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-connect-model.md) |
|
||||
| `turn_detection` | 语音活动检测（VAD）配置，推荐 `type: "semantic_vad"`（语义级 VAD）用于 `qwen3.5-omni-realtime` 系列 | AOQ/WebRTC 支持；WebSocket 部分模型需确认服务端兼容性 |
|
||||
| `x-dashscope-rtc-transport` | HTTP 请求头字段，值为 `"moq"` 表示 AOQ 协议 | **仅 AOQ 鉴权请求中必需**，见 [Token鉴权](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-token-authentication.md) |
|
||||
### 连接凭证参数（AOQ/WebRTC 共用）
|
||||
- `token`（AOQ）或 `API_KEY`（WebRTC/WS）：用于建连鉴权，**AOQ 必须使用网关返回的临时 `aoqTokenForClient`，而非原始 API Key**；WebRTC 和 WebSocket 可直接在 HTTP Header 中携带 `Authorization: Bearer <API_KEY>` [Token鉴权](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-token-authentication.md)。
|
||||
- `sid`：会话唯一标识，由网关分配。
|
||||
- `certFingerprint`（AOQ）：Relay TLS 证书指纹，用于安全校验。
|
||||
- `relayEndpoints`（AOQ）：客户端应连接的 Relay 接入点列表。
|
||||
- `workspaceIdHash`（AOQ）：工作区 ID 哈希，用于路由。
|
||||
|
||||
### 会话配置参数（`session.update` 事件）
|
||||
- `modalities`：输出模态数组，如 `["text", "audio"]` 或 `["text"]`。
|
||||
- `voice`：TTS 音色名称（如 `"Ethan"`）。
|
||||
- `input_audio_format` / `output_audio_format`：当前仅支持 `"pcm"`，采样率分别为 16 kHz（输入）和 24 kHz（输出）。
|
||||
- `instructions`：系统角色提示词。
|
||||
- `turn_detection`：语音活动检测配置，推荐 `semantic_vad` 类型（适用于 `qwen3.5-omni-realtime` 系列），含 `threshold` 和 `silence_duration_ms`。
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 1. 协议选型与 SDK 获取
|
||||
- **AOQ**：面向 Android/iOS/HarmonyOS 原生 App，需集成 [AOQ SDK](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-sdk-download.md)，并**必须下载 Opus [插件](../concepts/plugin.md)**（如 `libPluginOpus.zip`）以启用音频编解码。
|
||||
- **WebRTC**：无专用 SDK，Web 端直接使用浏览器原生 API；其他端可基于标准 WebRTC 库实现。需注意当前为白名单开放，需联系商务获取 Endpoint。
|
||||
- **WebSocket**：接入门槛最低，推荐服务端集成或原型验证，SDK 参见 [安装SDK](https://help.aliyun.com/zh/model-studio/install-sdk)。
|
||||
### 协议选型与接入路径
|
||||
- **AOQ**：适用于移动端原生应用（Android/iOS/HarmonyOS），需集成 [AOQ SDK](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-desc.md)，具备极致弱网对抗与内置 3A（回声消除/降噪/自动增益）。接入流程为：创建引擎 → 设置回调 → 获取网关凭证 → `connect` → 监听 `session.updated` → 启用媒体流。
|
||||
- **WebRTC**：适用于浏览器端或已有 WebRTC 基础设施的场景，无需专用 SDK，直接调用浏览器原生 API 或 `aiortc` 等库完成 SDP 交换与 ICE 连接。
|
||||
- **WebSocket**：适用于服务端集成或快速原型验证，接入门槛最低，通过 DashScope SDK 即可实现。
|
||||
|
||||
### 2. 鉴权流程
|
||||
所有协议均使用 `Authorization: Bearer <API_KEY>` 完成建连阶段鉴权：
|
||||
- **AOQ**：采用服务端代理模式——AppServer 携带 API Key 调用百炼 Allocate 接口获取 `aoqTokenForClient`、`sid`、`relayEndpoints` 等凭证，再下发给客户端 SDK 使用。
|
||||
- **WebRTC/WebSocket**：客户端或服务端直连时，在 SDP 交换（WebRTC）或 WebSocket 握手（WebSocket）请求头中携带 API Key。
|
||||
|
||||
### 3. 连接与媒体控制（以 AOQ 为例）
|
||||
- 创建引擎后，**必须先调用 `enableSendMediaStream(.audio, false)` 禁用发送**，避免在服务端未就绪时推送数据。
|
||||
- 连接成功后发送 `session.update` 配置会话；收到服务端 `session.updated` 事件后，再调用 `enableSendMediaStream(.audio, true)` 开启媒体流 [媒体流发送管理](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-media-stream-control.md)。
|
||||
- 音频/视频采集、播放、编码等高级功能（如自定义采集、外部音频流、视频帧回调）详见 [音频常用功能介绍](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-audio-features.md) 与 [视频常用功能介绍](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-video-features.md)。
|
||||
### 核心控制逻辑（AOQ）
|
||||
- **连接状态管理**：SDK 提供明确的状态机（`Connecting` → `Connected` → `Failed` → `Disconnected`），业务层需监听 `onConnectionStatusChange` 回调处理状态迁移 [连接状态管理](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/aoq-connection-management.md)。
|
||||
- **媒体流发送控制**：必须在收到 `session.updated` 服务端事件后，再调用 `enableSendMediaStream(.audio, true)` 启用音频发送；视频同理。此机制确保服务端已就绪，避免数据丢失 [媒体流发送管理](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/aoq-media-stream-control.md)。
|
||||
- **自定义音视频能力**：
|
||||
- **自定义音频采集**：通过 `isExternal=true` 关闭内部麦克风，调用 `addAudioExternalStream` 注册外部流，再循环 `pushAudioExternalStreamData` 推送 PCM 数据（建议 10ms/帧）[自定义音频采集](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/aoq-custom-audio-capture.md)。
|
||||
- **自定义视频输入**：支持原始帧（I420/NV12/BGRA）或编码帧（JPEG）两种模式，需设置 `isExternal=true` 并调用对应 `pushExternalVideo...Frame` 接口 [自定义视频输入](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/aoq-custom-video-input.md)。
|
||||
- **自定义音频播放**：设置 `isExternal=true` 后，通过 `setAudioFrameObserver` + `enableAudioFrameObserver` 获取解码后的 PCM 数据，交由应用层（如 Android `AudioTrack`）渲染 [自定义音频播放](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/aoq-custom-audio-playback.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **协议限制**：AOQ 不支持浏览器，WebRTC 不支持移动端原生 App（需 WebView 或第三方库桥接），WebSocket 无弱网对抗能力且无内置 AEC/降噪。
|
||||
- **模型限制**：`qwen3.5-omni-*` 系列模型要求 `turn_detection.type` 设为 `"semantic_vad"` 才能获得最佳响应效果；`Fun-ASR`/`CosyVoice` 等单模态模型**仅 WebSocket 可用**。
|
||||
- **安全限制**：API Key **严禁硬编码于客户端**，尤其 AOQ 客户端应只使用服务端下发的临时 `aoqTokenForClient`。
|
||||
- **状态管理**：AOQ SDK 连接状态机为 `Connecting → Connected/Failed → Disconnected`，其中 `Failed` 是瞬态，SDK 自动迁移至 `Disconnected`，业务层无需手动 `disconnect` [连接状态管理](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-connection-management.md)。
|
||||
- **自定义流注意事项**：使用外部音频/视频流时，需严格按文档要求设置 `isExternal=true`、管理 `streamId` 生命周期，并处理缓冲区满（错误码 110）等异常；原始帧推送需确保 `timeStamp` 准确，否则影响同步效果。
|
||||
- **协议兼容性限制**：AOQ 不支持浏览器环境；WebRTC 在非浏览器端需依赖第三方 WebRTC 库；WebSocket 无平台限制但缺乏弱网优化与内置 3A。
|
||||
- **模型协议绑定**：`multimodal-dialog`、Fun-ASR、CosyVoice 等模型**不支持 AOQ**，强行接入将失败；`qwen3.5-omni-*` 系列虽三协议均支持，但 AOQ 才能发挥其[多模态](../concepts/multi-modal.md)与弱网优势。
|
||||
- **AOQ SDK 集成要求**：必须下载并集成 Opus 编解码插件（`libPluginOpus`），否则无法启用 Opus 编码 [SDK下载](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-sdk-download.md)。
|
||||
- **安全规范**：API Key **严禁硬编码于客户端**，AOQ 必须通过服务端代理鉴权获取临时 [Token](../concepts/token.md)；WebRTC/WS 若由客户端直连，也应通过后端下发 [Token](../concepts/token.md) 或短期有效 Key。
|
||||
- **资源管理**：调用 `destroy()` 前，必须停止所有外部流推送循环（如 `mPushRunning = false`）并移除流（`removeAudioExternalStream`/`stopVideoCapture`），否则可能触发内存访问异常。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [Realtime API 概述](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-overview.md)
|
||||
- [SDK下载](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-sdk-download.md)
|
||||
- [接入模型与应用](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-connect-model.md)
|
||||
- [Token鉴权](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-token-authentication.md)
|
||||
- [AOQ SDK简介](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-desc.md)
|
||||
- [接入模型与应用](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-connect-model.md)
|
||||
- [SDK下载](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-sdk-download.md)
|
||||
- [Token鉴权](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-quick-start-guide/realtime-token-authentication.md)
|
||||
- [连接状态管理](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-connection-management.md)
|
||||
- [媒体流发送管理](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-media-stream-control.md)
|
||||
- [音频常用功能介绍](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-audio-features.md)
|
||||
- [自定义音频播放](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-custom-audio-playback.md)
|
||||
- [视频常用功能介绍](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-video-features.md)
|
||||
- [自定义音频采集](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-custom-audio-capture.md)
|
||||
- [视频常用功能介绍](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-video-features.md)
|
||||
- [自定义视频输入](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-custom-video-input.md)
|
||||
- [自定义音频播放](../../raw/model-api-reference/realtime-api-user-guide/realtime-api-aoq-api/realtime-api-aoq-sdk-function/aoq-custom-audio-playback.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,64 +1,91 @@
|
||||
# toolkits and [frameworks](frameworks.md)
|
||||
|
||||
阿里云百炼提供多种 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)及配套工具链，支持开发者无缝迁移现有应用。核心能力覆盖文本生成（Chat/Completions/Responses）、多模态理解（Vision）、向量化（Embedding）、文件处理（Files）、批量推理（Batch）、会话管理（Conversations）等场景，并兼容主流框架如 LangChain。所有接口均基于统一的 `compatible-mode/v1` 协议层，通过调整 `base_url`、`api_key` 和 `model` 即可快速接入。
|
||||
阿里云百炼提供多种 OpenAI 兼容的工具包与框架接口，支持开发者快速迁移现有应用。所有接口均基于标准 OpenAI REST API 协议设计，仅需调整 `base_url`、`api_key` 和模型名称即可接入，无需重写业务逻辑。核心能力覆盖文本生成、[多模态](../concepts/multi-modal.md)理解、向量嵌入、批量推理、对话状态管理及[文件处理](../concepts/file-processing.md)等场景。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
百炼支持的 OpenAI 兼容能力按协议类型划分，各接口支持的模型存在差异，需严格匹配：
|
||||
百炼支持的 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)按功能划分为以下几类：
|
||||
|
||||
- **Chat Completions 接口**：支持 Qwen 系列（`qwen-plus`、`qwen-flash`、`qwen3-*`）、Qwen-VL、Qwen-Coder、Qwen-Omni、Qwen-Math、DeepSeek（三方直供）、Kimi、GLM、MiniMax 等；但明确不支持 `Qwen-Audio` [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/compatibility-of-openai-with-dashscope.md)。
|
||||
- **Responses API**：专为智能体设计，仅支持 `qwen3-*` 系列模型（如 `qwen3.7-plus`、`qwen3.5-flash` 等），并内置联网搜索、网页抓取等工具能力 [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/compatibility-with-openai-responses-api.md)。
|
||||
- **Completions 接口**：当前仅支持 `qwen-coder-turbo`，用于代码补全与中间内容生成 [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/completions.md)。
|
||||
- **Vision 接口**：支持 `Qwen-VL`、`QVQ`、`Qwen-OCR`，其中 `QVQ` 仅支持[流式输出](../concepts/streaming-output.md) [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/qwen-vl-compatible-with-openai.md)。
|
||||
- **Embedding 接口**：支持 `text-embedding-v1` 至 `v4`，但**多模态 Embedding 模型（如 `qwen3-vl-embedding`）不支持 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)**，需使用专用多模态向量 API [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/embedding-interfaces-compatible-with-openai.md)。
|
||||
- **Files 接口**：支持 `purpose=file-extract`（文档分析）、`purpose=batch`（批量任务）、`purpose=fine-tune`（调优数据集），对应模型包括 `Qwen-Long`、`Qwen-Doc-Turbo` 及 Batch 支持的全部模型 [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/openai-file-interface.md)。
|
||||
- **Batch 接口**：分两种模式——文件批量（`/files` + `/batches`）和单请求同步批量（`/batch/chat/completions`），前者支持 `qwen3-*`、`deepseek-*`、`qwen-vl-*` 等数十种模型，后者仅支持部分文本与多模态模型 [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/batch-interfaces-compatible-with-openai.md)。
|
||||
- **Chat 接口**：支持 `qwen-plus`、`qwen-max`、`qwen-flash`、`qwen-long`、`qwen-vl-plus`、`qwen-ocr`、`deepseek-r1`、`kimi`、`glm`、`minimax` 等主流模型（含商业版与开源版），详见 [OpenAI Chat接口兼容](../../raw/model-api-reference/toolkits-and-frameworks/compatibility-of-openai-with-dashscope.md)；
|
||||
- **Vision 接口**：专为视觉理解优化，支持 `qwen-vl-plus`、`qvq`、`qwen-ocr`，其中 `qvq` 仅支持[流式输出](../concepts/streaming-output.md)；
|
||||
- **Embedding 接口**：支持 `text-embedding-v1` 至 `v4` 全系列文本向量模型，支持多语种及可选维度（`v3/v4` 支持 `dimensions` 参数）；
|
||||
- **Completions 接口**：面向代码补全等场景，当前仅支持 `qwen-coder-turbo`（见 [completions 接口](../../raw/model-api-reference/toolkits-and-frameworks/completions.md)）；
|
||||
- **Conversations 接口**：提供会话生命周期管理（创建、查询、更新、删除、追加消息），适用于跨设备长周期对话；
|
||||
- **Files 接口**：支持上传文件用于文档问答（`purpose=file-extract`）、批量任务（`purpose=batch`）或模型调优（`purpose=fine-tune`）；
|
||||
- **Batch 接口**：包含两种模式——
|
||||
- **Batch Chat**（单请求同步等待）：通过 `https://batch.dashscope.aliyuncs.com/compatible-mode/v1` 调用，适用于低频高成本场景；
|
||||
- **Batch File**（JSONL 文件异步提交）：支持千级并发，费用为实时调用的 50%，详见 [OpenAI兼容-Batch（文件输入）](../../raw/model-api-reference/toolkits-and-frameworks/batch-interfaces-compatible-with-openai.md)。
|
||||
|
||||
> **注意**：文档 6（Batch 文件输入）与文档 7（Batch Chat）对同一模型（如 `qwen3.7-plus`）的适用性描述一致，但文档 7 明确要求“单次请求”，而文档 6 要求 JSONL 文件格式；二者本质是不同调用范式，无矛盾。
|
||||
> **注意**：文档 1 和文档 2 均强调北京/新加坡地域应迁移到业务空间专属域名（`{WorkspaceId}.cn-beijing.maas.aliyuncs.com`），但文档 3（Completions）仍使用旧域名 `https://dashscope.aliyuncs.com`，该接口**仅适用于华北2（北京）地域且未更新域名**，存在过时风险。
|
||||
> **注意**：`Qwen-Audio` 明确不支持 OpenAI 兼容协议，仅支持 DashScope 原生协议；`qwen3.5-omni-plus` 在 Batch 场景下不支持语音输出，且 `qwen3.7`/`qwen3.6`/`qwen3.5` 系列模型默认开启思考模式，需显式设置 `enable_thinking=false` 关闭以避免额外 token 成本。
|
||||
|
||||
## 关键参数
|
||||
|
||||
所有 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)共用以下核心参数，行为与 OpenAI 官方一致，但部分参数有百炼特有约束：
|
||||
所有 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)共用以下核心参数：
|
||||
|
||||
- `base_url`：必须设置为对应地域的兼容端点，例如北京地域为 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`；弗吉尼亚、东京、法兰克福等地域无需 `{WorkspaceId}` [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/compatibility-of-openai-with-dashscope.md)。
|
||||
- `model`：必须为百炼实际支持的模型名，不可直接复用 OpenAI 的 `gpt-4` 等名称；模型列表需查阅各接口文档，例如 Responses API 不接受 `qwen-plus` [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/compatibility-with-openai-responses-api.md)。
|
||||
- `stream` 与 `stream_options`：流式响应时，`stream_options={"include_usage": true}` 可在最后一 chunk 返回 token 统计，该行为在 Chat、Vision、Responses 接口中均有效。
|
||||
- `temperature` / `top_p`：二者互斥，建议只设置其一；`temperature` 取值范围 `[0, 2.0)`，`top_p` 为 `(0, 1.0]`。
|
||||
- `max_tokens`：仅控制响应截断，**不影响模型实际生成长度**；若模型输出超限，返回内容将被截断。
|
||||
- `stop`：支持字符串或 token ID 数组，可用于敏感词拦截。
|
||||
- `seed`：设置后提升结果确定性，取值范围 `0` 至 `2^31-1`。
|
||||
- `presence_penalty`：控制重复度，范围 `[-2.0, 2.0]`，正值抑制重复。
|
||||
- `enable_thinking`：仅 Batch 场景下生效，`qwen3.*` 系列模型默认开启思考模式，显式设为 `false` 可避免额外 token 成本 [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/batch-interfaces-compatible-with-openai.md)。
|
||||
| 参数 | 类型 | 必选 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `model` | string | 是 | 模型名称，如 `qwen-plus`、`text-embedding-v4`、`qwen-vl-plus` 等 |
|
||||
| `base_url` | string | 是 | 服务端点，**必须使用业务空间专属域名**（如 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`），旧域名（`dashscope.aliyuncs.com`）已不推荐使用（见 [OpenAI Chat接口兼容](../../raw/model-api-reference/toolkits-and-frameworks/compatibility-of-openai-with-dashscope.md)） |
|
||||
| `api_key` | string | 是 | 百炼 API Key，建议通过环境变量 `DASHSCOPE_API_KEY` 配置以降低泄露风险 |
|
||||
|
||||
通用可选参数：
|
||||
- `temperature` / `top_p`：控制生成多样性，二者建议只设其一；
|
||||
- `max_tokens`：限制输出长度，超限将截断（不影响模型内部生成过程）；
|
||||
- `stream` + `stream_options={"include_usage": true}`：启用[流式输出](../concepts/streaming-output.md)并在末尾返回 token 统计；
|
||||
- `stop`：指定终止字符串，可用于敏感词过滤；
|
||||
- `seed`：设置随机种子以获得确定性输出（范围 `0–2^31−1`）；
|
||||
- `presence_penalty`：抑制重复内容（范围 `[-2.0, 2.0]`）。
|
||||
|
||||
模型特有参数：
|
||||
- Embedding：`dimensions`（仅 `v3/v4` 支持）、`encoding_format`（`float` 或 `base64`）；
|
||||
- Conversations：`metadata`（结构化元数据，≤16 对键值对）；
|
||||
- Batch File：`completion_window`（最长等待时间，如 `"24h"`）、`enable_thinking`（与 `model` 同级，不可置于 `extra_body` 内）。
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 基础调用流程
|
||||
1. **获取凭证**：在百炼控制台开通服务并获取对应地域的 API Key，**强烈建议配置到环境变量 `DASHSCOPE_API_KEY`**，避免硬编码泄露风险。
|
||||
2. **配置端点**：根据接口类型与地域选择 `base_url`，北京/新加坡务必使用 `{WorkspaceId}` 专属域名以获得最佳性能。
|
||||
3. **构造请求**：按接口规范传入 `model`、`messages`（Chat）、`input`（Responses）、`prompt`（Completions）等必选参数。
|
||||
4. **处理响应**：非流式返回完整 JSON；流式需按 chunk 解析，注意 `finish_reason` 和末尾含 `usage` 的 chunk。
|
||||
### SDK 调用（推荐）
|
||||
- **Python**：安装 `openai>=1.0.0` 或 `langchain_openai`，初始化时传入 `base_url` 和 `api_key`：
|
||||
```python
|
||||
from openai import OpenAI
|
||||
client = OpenAI(
|
||||
api_key=os.getenv("DASHSCOPE_API_KEY"),
|
||||
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
|
||||
)
|
||||
# Chat
|
||||
client.chat.completions.create(model="qwen-plus", messages=[...])
|
||||
# Embedding
|
||||
client.embeddings.create(model="text-embedding-v4", input="hello")
|
||||
# Files
|
||||
client.files.create(file=Path("doc.pdf"), purpose="file-extract")
|
||||
# Conversations
|
||||
client.conversations.create(items=[{"role":"system","content":"..."}])
|
||||
```
|
||||
- **Node.js/Java/Go/C#**：同理配置 `baseURL` 或 `baseUrl`，调用对应方法（详见各文档示例）。
|
||||
|
||||
### 框架集成
|
||||
- **LangChain**：推荐使用 `langchain_openai`（兼容部分模型）或 `langchain-community` + `dashscope`（支持全部模型）。`ChatOpenAI` 构造时需指定 `base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"`；`ChatTongyi` 则使用原生 DashScope SDK，支持更多模型与高级特性 [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/use-bailian-in-langchain.md)。
|
||||
- **批量任务**：优先使用文件批量（`/files` + `/batches`），上传 JSONL 后轮询状态；若只需单请求延迟容忍，可用 `/batch/chat/completions` 并设置 `timeout`（最长 3600 秒）[原文标题](../../raw/model-api-reference/toolkits-and-frameworks/openai-compatible-batch-chat.md)。
|
||||
- **上下文管理**：
|
||||
- Responses API：通过 `previous_response_id` 自动关联历史，无需维护消息数组；
|
||||
- Conversations API：创建会话后调用 `/conversations/{id}/items` 追加消息，实现跨设备持久化 [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/openai-compatible-conversations.md)。
|
||||
### HTTP 直连
|
||||
- 所有接口均支持标准 REST 调用，`Authorization: Bearer ${DASHSCOPE_API_KEY}` + `Content-Type: application/json`；
|
||||
- Endpoint 示例：
|
||||
- Chat：`POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions`
|
||||
- Embedding：`POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings`
|
||||
- Conversations：`POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations`
|
||||
|
||||
### LangChain 集成
|
||||
- **OpenAI 方式**：使用 `langchain_openai.ChatOpenAI`，仅支持部分模型（见 [在LangChain中使用阿里云百炼](../../raw/model-api-reference/toolkits-and-frameworks/use-bailian-in-langchain.md)）；
|
||||
- **DashScope 原生方式**：使用 `langchain_community.chat_models.tongyi.ChatTongyi`，支持全部百炼文本模型，推荐用于生产环境。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域与域名绑定**：API Key 与 `base_url` 必须匹配同一地域（如北京 Key 配北京 URL），否则返回 `invalid_api_key` 错误；旧域名（`dashscope.aliyuncs.com`）虽仍可用，但文档 1、2、4、8 均明确建议迁移至 `{WorkspaceId}` 专属域名以提升稳定性。
|
||||
- **模型能力隔离**：同一模型在不同接口中能力不同，例如 `qwen-plus` 在 Chat 接口可用，但在 Responses 接口不可用；`Qwen-Audio` 完全不支持 OpenAI 协议 [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/compatibility-of-openai-with-dashscope.md)。
|
||||
- **文件服务配额**：`/files` 接口总存储上限 100 GB、最多 10,000 个文件；单文件大小限制依 `purpose` 而异：`file-extract` 最大 150 MB，`batch` 最大 500 MB，`fine-tune` 最大 300 MB [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/openai-file-interface.md)。
|
||||
- **Batch 超时机制**：文件批量任务最长等待 24 小时；单请求同步批量（Batch Chat）默认超时 3600 秒，需在客户端显式设置 `timeout` 参数。
|
||||
- **三方模型可用性**：DeepSeek、Kimi 等三方直供模型**仅在中国站内地地域可用**，且需在控制台单独开通服务 [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/compatibility-of-openai-with-dashscope.md)。
|
||||
- **错误处理**：所有接口遵循 OpenAI 错误格式（`error.code` + `error.message`），常见错误码详见官方文档；调试时建议先用 `batch-test-model` 验证链路 [原文标题](../../raw/model-api-reference/toolkits-and-frameworks/batch-interfaces-compatible-with-openai.md)。
|
||||
- **地域与域名**：北京、新加坡、东京、弗吉尼亚四地均提供专属 `WorkspaceId` 域名，**强烈建议迁移**（旧域名 `dashscope.aliyuncs.com` 性能与稳定性较低）；
|
||||
- **三方模型可用性**：`DeepSeek`、`Kimi`、`GLM`、`MiniMax` 等仅在中国内地地域可用，调用前须在控制台开通对应服务；
|
||||
- **文件限制**：`files` 接口总存储上限 100 GB / 10000 个文件；`file-extract` 单文件 ≤150 MB，`batch` 单文件 ≤500 MB，`fine-tune` 单文件 ≤300 MB；
|
||||
- **Batch 超时**：Batch Chat 默认超时 3600 秒（1 小时），Batch File 任务最长等待 `completion_window`（如 `"24h"`）；
|
||||
- **Qwen-Audio 不兼容**：该模型明确不支持 OpenAI 协议，需改用 DashScope 原生 SDK；
|
||||
- **[函数调用](../concepts/function-calling.md)（Function Calling）**：仅 `chat.completions` 接口支持，`completions` 接口不支持（见 [completions 接口](../../raw/model-api-reference/toolkits-and-frameworks/completions.md)）；
|
||||
- **[多模态](../concepts/multi-modal.md)输入**：`qwen-vl-plus` 等模型支持 `image_url`（HTTP URL 或 `data:image/...` Base64），但 `completions` 接口不支持图像输入。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [OpenAI Chat接口兼容](../../raw/model-api-reference/toolkits-and-frameworks/compatibility-of-openai-with-dashscope.md)
|
||||
- [OpenAI Responses接口兼容](../../raw/model-api-reference/toolkits-and-frameworks/compatibility-with-openai-responses-api.md)
|
||||
- [completions 接口](../../raw/model-api-reference/toolkits-and-frameworks/completions.md)
|
||||
- [OpenAI Vision接口兼容](../../raw/model-api-reference/toolkits-and-frameworks/qwen-vl-compatible-with-openai.md)
|
||||
- [OpenAI文件接口兼容](../../raw/model-api-reference/toolkits-and-frameworks/openai-file-interface.md)
|
||||
|
||||
@@ -1,68 +1,98 @@
|
||||
# vector and sort
|
||||
|
||||
`vector and sort` 是百炼平台提供的核心向量化与排序能力集合，涵盖文本、多模态内容的嵌入（embedding）生成及跨模态/纯文本的精细化重排序（rerank）。该能力支撑语义搜索、RAG、推荐系统、聚类分析等典型AI应用，支持同步/异步调用、OpenAI兼容接口及SDK封装，适用于从单条短文本到百万级[Token](../concepts/token.md)批量处理的多样化场景。所有模型均基于阿里云自研大模型底座，提供多语言、多维度、多模态统一语义空间支持。
|
||||
百炼平台的 `vector and sort` 功能涵盖文本/[多模态](../concepts/multi-modal.md)向量化（embedding）与文本排序（rerank）两大核心能力，分别用于将非结构化内容映射到语义向量空间、以及对召回结果进行精细化相关性重排序。二者常协同用于 RAG、搜索引擎、推荐系统等场景，支持同步、异步及 OpenAI 兼容调用方式。
|
||||
|
||||
## 支持的模型与功能
|
||||
|
||||
### 文本向量模型（Embedding）
|
||||
- **同步模型**：`qwen3.7-text-embedding`（最高128K [Token](../concepts/token.md)输入）、`text-embedding-v4`（支持动态`dimensions`参数，含2048/1536/1024等可选维度）、`text-embedding-v3`、`text-embedding-v2`、`text-embedding-v1`。详见 [同步接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-synchronous-api.md)。
|
||||
- **异步批处理模型**：`text-embedding-async-v2`（1536维，单次最多10万行）、`text-embedding-async-v1`。适用于超大批量文件（≤200MB）的离线向量化任务，需通过任务ID轮询结果。详见 [批处理接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-batch-api.md)。
|
||||
- **多模态向量模型**：`qwen3-vl-embedding`（支持独立/融合向量）、`qwen2.5-vl-embedding`（仅融合）、`tongyi-embedding-vision-plus-2026-03-06`（Qwen3底座，支持`res_level`和`max_video_frames`）、`multimodal-embedding-v1`等。支持文本、图像、视频任意组合输入，并在同一语义空间生成向量。详见 [Multimodal-Embedding API详情](../../raw/model-api-reference/vector-and-sort/multimodal-vector/multimodal-embedding-api-reference.md)。
|
||||
### 向量化模型（Embedding）
|
||||
|
||||
- **通用文本向量**：支持 `qwen3.7-text-embedding`、`text-embedding-v4`、`text-embedding-v3`、`text-embedding-v2`、`text-embedding-v1` 等版本，适用于纯文本语义表征 [同步接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-synchronous-api.md)。
|
||||
- **批处理文本向量**：`text-embedding-async-v2` / `text-embedding-async-v1`，专为超大批量（单次最多 100,000 行）文本设计，采用异步任务模式 [批处理接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-batch-api.md)。
|
||||
- **[多模态](../concepts/multi-modal.md)向量**：`qwen3-vl-embedding`、`qwen2.5-vl-embedding`、`tongyi-embedding-vision-plus-2026-03-06` 等，支持文本、图像、视频及其组合输入，并提供独立向量与融合向量两种生成模式 [Multimodal-Embedding API详情](../../raw/model-api-reference/vector-and-sort/multimodal-vector/multimodal-embedding-api-reference.md)。
|
||||
|
||||
### 排序模型（Rerank）
|
||||
- **纯文本排序**：`qwen3-rerank`（OpenAI兼容接口，最大500文档，单文档4K [Token](../concepts/token.md)），推荐替代已下线的`gte-rerank`系列。
|
||||
- **多模态排序**：`qwen3-vl-rerank`（支持文本/图片/视频混合查询与文档，最大100文本/40图片/4视频），适用于跨模态检索场景。
|
||||
- **历史模型**：`gte-rerank-v2`仍可用但不推荐新项目使用；其将于2026年5月30日下线，迁移指引见 [文本排序](../../raw/model-api-reference/vector-and-sort/rerank-model/text-rerank-api.md)。
|
||||
|
||||
> **注意**：文档1中列出的`text-embedding-async-v1`在文档2的模型概览表中未体现语种支持完整性（仅列“中文、英语…”），而文档2明确说明`qwen3.7-text-embedding`支持201种语种，`text-embedding-v4`支持100+语种。实际开发应以文档2为准，`async-v1`为旧版模型，建议优先选用`async-v2`或同步模型。
|
||||
- **纯文本排序**：`qwen3-rerank`（推荐）、`gte-rerank-v2`（即将下线），支持 query-document 相关性打分与 top-k 截断。
|
||||
- **[多模态](../concepts/multi-modal.md)排序**：`qwen3-vl-rerank`，支持文本、图片、视频作为 query 或 document 的任意组合排序，适用于跨模态检索 [文本排序](../../raw/model-api-reference/vector-and-sort/rerank-model/text-rerank-api.md)。
|
||||
> **注意**：`gte-rerank` 系列模型将于 2026 年 05 月 30 日下线，新项目请优先选用 `qwen3-rerank` 或 `qwen3-vl-rerank`。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 适用模型 | 说明 | 示例值 |
|
||||
|------|----------|------|--------|
|
||||
| `model` | 全部 | 必选，指定模型名称 | `"qwen3-rerank"`, `"qwen3-vl-embedding"` |
|
||||
| `input` / `documents` / `query` | 按模型区分 | 同步embedding：`input`支持`string`/`array<string>`/`file`；rerank：`query`+`documents`分离；多模态：`input.contents`为对象数组 | `{"text": "hello"}`, `[{"image": "url"}, {"text": "desc"}]` |
|
||||
| `dimensions` | `qwen3.7-text-embedding`, `text-embedding-v3/v4`, `qwen3-vl-embedding`, `tongyi-embedding-vision-plus-2026-03-06`等 | 可选，指定输出向量维度（非所有模型都支持） | `1024`, `2048` |
|
||||
| `enable_fusion` | 仅`qwen3-vl-embedding` | 布尔值，启用后将`contents`中所有模态融合为单个向量 | `true` |
|
||||
| `top_n` | `qwen3-rerank`, `qwen3-vl-rerank`, `gte-rerank-v2` | 可选，返回前N个最相关结果 | `5` |
|
||||
| `instruct` | `qwen3-rerank`, `qwen3-vl-rerank` | 可选，英文指令引导排序策略（如问答检索或语义相似度） | `"Given a web search query, retrieve relevant passages..."` |
|
||||
| `fps` | `qwen3-vl-rerank`, `qwen3-vl-embedding` | 可选，视频帧采样率（0.0–1.0） | `0.5` |
|
||||
| 参数名 | 类型 | 说明 | 适用模型 |
|
||||
|--------|------|------|----------|
|
||||
| `model` | string | 必填，指定模型名称（如 `"text-embedding-v4"`、`"qwen3-rerank"`） | 全部 |
|
||||
| `input` / `documents` / `query` | string / array / object | 输入内容格式因模型而异：<br>- 文本向量：支持 string、string[]、file；<br>- Rerank：`qwen3-rerank` 要求 `query` 和 `documents` 平级；`qwen3-vl-rerank` 要求嵌套在 `input` 对象中 | 全部 |
|
||||
| `dimensions` | integer | 指定向量维度（如 `1024`），仅部分模型支持（`text-embedding-v3/v4`、`qwen3-vl-embedding` 等） | 文本/多模态向量 |
|
||||
| `enable_fusion` | boolean | 仅 `qwen3-vl-embedding` 支持，设为 `true` 时融合所有输入为单向量 | 多模态向量 |
|
||||
| `top_n` | integer | 返回最相关的前 N 个结果，默认返回全部 | Rerank |
|
||||
| `instruct` | string | 自定义排序任务指令（如 `"Retrieve semantically similar text."`），影响排序策略，仅 `qwen3-rerank` / `qwen3-vl-rerank` 生效 | Rerank |
|
||||
| `encoding_format` | string | 当前仅支持 `"float"` | 文本向量（同步） |
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 接口选择
|
||||
- **小规模实时向量生成**（≤25条文本或单图/单视频）：使用同步API，HTTP endpoint为 `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings`（OpenAI兼容）或 `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding`（DashScope原生）。
|
||||
- **大规模离线批处理**（100行–10万行文本）：必须使用异步批处理API，先`POST`创建任务，再`GET /api/v1/tasks/{task_id}`轮询结果。详见 [批处理接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-batch-api.md)。
|
||||
- **多模态向量/排序**：统一使用 `POST https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding`（embedding）或 `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank`（rerank）。
|
||||
### 同步调用（文本向量）
|
||||
通过 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)或 DashScope SDK 调用，适合小批量（≤20 条）实时请求：
|
||||
```python
|
||||
from openai import OpenAI
|
||||
client = OpenAI(
|
||||
api_key=os.getenv("DASHSCOPE_API_KEY"),
|
||||
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
|
||||
)
|
||||
resp = client.embeddings.create(
|
||||
model="text-embedding-v4",
|
||||
input=["文本1", "文本2"],
|
||||
dimensions=1024
|
||||
)
|
||||
```
|
||||
|
||||
### SDK调用要点
|
||||
- DashScope SDK支持Python/Java，参数名与HTTP一致但结构扁平化（如`BatchTextEmbedding.call()`直接传`url`, `text_type`，无需嵌套`input`对象）。
|
||||
- OpenAI SDK兼容模式需配置`base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"`，并使用`client.embeddings.create()`。
|
||||
- 多模态排序SDK调用时，`query`和`documents`可直接传入字典（如`{"image": "url"}`），无需手动构造`input`对象。
|
||||
### 异步调用（批处理向量）
|
||||
适用于海量文本（100,000 行以内），需先创建任务再轮询结果：
|
||||
```python
|
||||
from dashscope import BatchTextEmbedding
|
||||
result = BatchTextEmbedding.call(
|
||||
model=BatchTextEmbedding.Models.text_embedding_async_v2,
|
||||
url="https://your-bucket/object.txt",
|
||||
text_type="document"
|
||||
)
|
||||
# 后续通过 task_id 查询结果
|
||||
```
|
||||
|
||||
### Rerank 调用
|
||||
区分模型选择不同 endpoint：
|
||||
- `qwen3-rerank`：使用 `/compatible-api/v1/reranks`（OpenAI 兼容风格）
|
||||
- `qwen3-vl-rerank` / `gte-rerank-v2`：使用 `/api/v1/services/rerank/text-rerank/text-rerank`（DashScope 原生风格）
|
||||
示例（`qwen3-rerank`）：
|
||||
```python
|
||||
resp = dashscope.TextReRank.call(
|
||||
model="qwen3-rerank",
|
||||
query="用户问题",
|
||||
documents=["候选文档1", "候选文档2"],
|
||||
top_n=3
|
||||
)
|
||||
```
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **Token与尺寸限制**：
|
||||
- `qwen3.7-text-embedding`单字符串最长128K Token；`text-embedding-v4`单字符串限8,192 Token；`text-embedding-async-v2`单行限2,048 Token且单次最多100,000行。
|
||||
- 多模态模型中，`qwen3-vl-embedding`图片≤10MB、视频≤50MB；`tongyi-embedding-vision-plus`图片≤3MB、视频≤10MB。
|
||||
- `qwen3-rerank`单次请求最大Token数为120,000（计算公式：`Query Tokens × Document 数量 + Document Tokens 总和`）。
|
||||
- **[Token](../concepts/token.md) 与行数限制**：
|
||||
- `qwen3.7-text-embedding` 单条最长 128,000 [Token](../concepts/token.md)，批量最多 20 行；
|
||||
- `text-embedding-v4` 单条最长 8,192 [Token](../concepts/token.md)，批量最多 10 行；
|
||||
- `text-embedding-async-v2` 单次最多 100,000 行，单行 ≤2,048 Token；
|
||||
- `qwen3-rerank` 单次请求总 Token 上限为 `Query Tokens × Document 数 + Document Tokens 总和 ≤ 120,000`。
|
||||
|
||||
- **地域与Endpoint差异**：
|
||||
- 北京地域使用`cn-beijing.maas.aliyuncs.com`；新加坡地域需替换为`ap-southeast-1.maas.aliyuncs.com`（见 [批处理接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-batch-api.md)）。
|
||||
- `qwen3-rerank`使用`/compatible-api/v1/reranks`，其余rerank模型使用`/api/v1/services/rerank/...`，不可混用。
|
||||
- **地域与 endpoint 差异**：
|
||||
> **注意**：文档中 `text-embedding-batch-api.md` 明确要求 HTTP 调用必须携带 `X-DashScope-Async: enable` 请求头，否则报错“current user api does not support synchronous calls”；而 `text-embedding-synchronous-api.md` 的 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)默认为同步，两者 endpoint 和鉴权方式不可混用 [批处理接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-batch-api.md)。
|
||||
|
||||
- **[异步任务](../concepts/asynchronous-task.md)生命周期**：
|
||||
- [异步任务](../concepts/asynchronous-task.md)ID有效期24小时，结果URL仅保留24小时，需及时下载。
|
||||
- 单用户并发运行中异步作业上限为3个，排队中+运行中总数不超过50个（见 [批处理接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-batch-api.md)）。
|
||||
- **免费额度与有效期**：
|
||||
所有模型均提供开通后 90 天内的免费额度（如 `qwen3.7-text-embedding` 为 100 万 Token），详见各模型概览表格 [同步接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-synchronous-api.md)。
|
||||
|
||||
- **模型弃用提醒**：
|
||||
> **注意**：`gte-rerank`系列模型（包括`gte-rerank-v2`）将于2026年5月30日下线，新项目请务必使用`qwen3-rerank`或`qwen3-vl-rerank`。迁移影响包括接口路径、参数结构（`qwen3-rerank`无`input`嵌套层）及计费单价变化。
|
||||
- **多模态输入规范**：
|
||||
图片/视频 URL 必须公开可访问；Base64 图片需符合 `data:image/{format};base64,{data}` 格式；`qwen2.5-vl-embedding` 不支持 `multi_images`，且仅返回融合向量 [Multimodal-Embedding API详情](../../raw/model-api-reference/vector-and-sort/multimodal-vector/multimodal-embedding-api-reference.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [批处理接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-batch-api.md)
|
||||
- [同步接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-synchronous-api.md)
|
||||
- [Multimodal-Embedding API详情](../../raw/model-api-reference/vector-and-sort/multimodal-vector/multimodal-embedding-api-reference.md)
|
||||
- [批处理接口API详情](../../raw/model-api-reference/vector-and-sort/general-text-vector/text-embedding-batch-api.md)
|
||||
- [文本排序](../../raw/model-api-reference/vector-and-sort/rerank-model/text-rerank-api.md)
|
||||
- [Multimodal-Embedding API详情](../../raw/model-api-reference/vector-and-sort/multimodal-vector/multimodal-embedding-api-reference.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,96 +1,107 @@
|
||||
# video generation api
|
||||
|
||||
百炼平台的 Video Generation API 提供多种视频生成与编辑能力，涵盖文生视频（T2V）、图生视频（I2V）、参考生视频（R2V）、视频编辑、数字人驱动、口型同步等场景。所有模型均采用异步调用模式，通过 `task_id` 轮询获取结果，任务有效期为 24 小时。开发者需确保模型、Endpoint URL 与 API Key 严格同地域部署。
|
||||
百炼平台的 Video Generation API 提供多种视频生成与编辑能力，包括文生视频、图生视频（首帧/首尾帧）、参考生视频、视频编辑、风格重绘、口型同步等。所有接口均采用异步调用模式，需通过 `task_id` 轮询获取结果，任务 ID 有效期为 24 小时。开发者需确保模型、Endpoint URL 与 API Key 严格同地域，跨地域调用将失败 [HappyHorse-文生视频API参考](../../raw/model-api-reference/video-generation-api/happyhorse-api-reference/happyhorse-text-to-video-api-reference.md)。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
Video Generation API 支持以下主流模型及对应能力：
|
||||
API 支持多系列模型，按能力划分如下：
|
||||
|
||||
- **万相系列（wan2.7）**：统一新版协议，支持首帧/首尾帧/视频续写三类图生视频、文生视频（含多镜头叙事）、参考生视频（图像+视频+音频多模态融合）、视频编辑（风格迁移、局部替换）[万相2.7-图生视频API参考](../../raw/model-api-reference/video-generation-api/wan-api-reference/image-to-video-general-api-reference.md)。
|
||||
- **HappyHorse 系列**：提供图生视频（基于首帧）、参考生视频（多图融合）、视频编辑（指令+参考图）三类能力，适用于物理真实感强的运动建模 [HappyHorse-图生视频-基于首帧API参考](../../raw/model-api-reference/video-generation-api/happyhorse-api-reference/happyhorse-image-to-video-api-reference.md)。
|
||||
- **可灵（Kling）**：支持文生视频、图生视频（首帧/首尾帧）、参考生视频及视频编辑，强调高保真动态与构图控制 [可灵-视频生成API文档](../../raw/model-api-reference/video-generation-api/kling-api-reference/kling-video-generation-api-reference.md)。
|
||||
- **爱诗（PixVerse）**：覆盖图生视频（首帧/首尾帧）、文生视频、参考生视频、视频对口型、动作模仿、视频超清、视频风格重绘等细分能力 [爱诗-图生视频-基于首帧API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-image-to-video-api-reference.md)。
|
||||
- **Vidu**：专注文生视频与图生视频（首帧/首尾帧），强调影视级画质与节奏控制。
|
||||
- **数字人与肖像动画**：包括万相-s2v（音画同步）、LivePortrait（轻量播报）、EMO（唱演）、AnimateAnyone（舞蹈复刻）、VideoRetalk（口型替换）、Emoji（表情包）等专用模型，均需先调用 `detect` 模型校验输入合规性。
|
||||
- **视频后处理**：如 Vidu/VideoStyleTransform（8种艺术风格重绘）、PixVerse-upscale（4K超分）等独立功能模型。
|
||||
- **文生视频（T2V）**：`happyhorse-1.1-t2v`、`wan2.7-t2v-*`、`pixverse-c1-t2v`、`vidu/viduq3-turbo_text2video`、`kling/kling-v3-video-generation`
|
||||
- **图生视频（I2V）**：
|
||||
- 首帧：`happyhorse-1.1-i2v`、`wan2.7-i2v`、`pixverse-c1-it2v`、`vidu/viduq3-pro-fast_img2video`
|
||||
- 首尾帧：`pixverse-c1-kf2v`、`vidu/viduq3-turbo_start-end2video`、`wan2.2-kf2v-fla`（旧版）
|
||||
- **参考生视频（R2V）**：`happyhorse-r2v`、`wan2.7-r2v-*`、`pixverse-c1-r2v`、`vidu/viduq3-ad_reference2video`
|
||||
- **视频编辑**：`happyhorse-videoedit`、`wan2.7-videoedit`、`wanx2.1-vace-plus`（旧版）
|
||||
- **专用功能模型**：
|
||||
- 对口型：`pixverse/pixverse-lipsync`
|
||||
- 动作模仿：`pixverse/pixverse-motioncontrol`
|
||||
- 视频超清：`pixverse/pixverse-upscale`
|
||||
- 风格重绘：`video-style-transform`
|
||||
- 数字人/播报：`wan2.2-s2v`、`liveportrait`、`emo-v1`、`videoretalk`
|
||||
- 图生动作/换人：`wan2.2-animate-move`、`wan2.2-animate-mix`
|
||||
|
||||
> **注意**：万相2.1–2.6 系列（如 `wan2.2-kf2v-fla`、`wanx2.1-vace-plus`）使用旧版协议，Endpoint 路径为 `/api/v1/services/aigc/image2video/video-synthesis`，而万相2.7 及所有新模型（HappyHorse、Kling、PixVerse、Vidu）统一使用 `/api/v1/services/aigc/video-generation/video-synthesis`。混用路径将导致 404 错误 [万相-首尾帧生视频API参考（2.2）](../../raw/model-api-reference/video-generation-api/wan-api-reference/legacy-video-models/legacy-image-to-video-by-first-and-last-frame-api-reference.md)。
|
||||
> **注意**：万相 2.7 系列（如 `wan2.7-i2v`、`wan2.7-t2v-*`）为当前推荐版本，支持首帧/首尾帧/视频续写三合一能力；而 `wan2.6` 及更早版本（如文档30–34所列）仅支持单一任务类型，且部分使用旧版 endpoint `/api/v1/services/aigc/image2video/`，已逐步淘汰 [万相2.7-图生视频API参考](../../raw/model-api-reference/video-generation-api/wan-api-reference/image-to-video-general-api-reference.md)。
|
||||
|
||||
## 关键参数
|
||||
|
||||
所有请求必须包含以下基础参数：
|
||||
所有请求需包含以下必选字段：
|
||||
|
||||
- **`model`**（必填）：模型标识符，如 `"wan2.7-t2v-2026-06-12"`、`"pixverse/pixverse-c1-t2v"`、`"vidu/viduq3-turbo_text2video"`。不同模型支持的子能力由 model name 决定。
|
||||
- **`input`**（必填）：结构化输入数据：
|
||||
- 文生视频：`{"prompt": "..."}`；
|
||||
- 图生视频：`{"media": [{"type": "image_url", "url": "..."}], "prompt": "..."}`；
|
||||
- 首尾帧：`{"media": [{"type": "first_frame", "url": "..."}, {"type": "last_frame", "url": "..."}], "prompt": "..."}`；
|
||||
- 参考生视频：`{"media": [{"type": "reference_image", "url": "..."}, ...], "prompt": "..."}`；
|
||||
- 数字人：`{"image_url": "...", "audio_url": "..."}`（需先通过 detect）。
|
||||
- **`parameters`**（可选）：控制输出质量与行为：
|
||||
- `resolution`（如 `"720P"`、`"540P"`、`"1280*720"`）；
|
||||
- `duration`（秒数，通常 3–5 秒）；
|
||||
- `watermark`（布尔值，默认 `true`）；
|
||||
- `aspect_ratio`（如 `"16:9"`）；
|
||||
- `style_level`（EMO 等模型特有）；
|
||||
- `seed`（固定随机性）。
|
||||
- `model`：模型标识符（如 `"wan2.7-t2v-2026-06-12"`），必须与所选模型精确匹配
|
||||
- `input`：输入数据结构，依任务类型变化：
|
||||
- 文生视频：`{"prompt": "..."}`
|
||||
- 图生视频：`{"media": [{"type": "image_url", "url": "..."}], "prompt": "..."}`
|
||||
- 首尾帧：`{"media": [{"type": "first_frame", "url": "..."}, {"type": "last_frame", "url": "..."}], "prompt": "..."}`
|
||||
- 参考生视频：`{"media": [{"type": "reference_image", "url": "..."}, ...], "prompt": "..."}`
|
||||
- 视频编辑/对口型：`{"media": [{"type": "video", "url": "..."}, {"type": "audio", "url": "..."}]}`
|
||||
- `parameters`（可选）：控制输出质量与时长，常见字段：
|
||||
- `duration`: 视频时长（秒），通常支持 3–5 秒（部分模型支持最长 10 秒）
|
||||
- `resolution` / `size`: 分辨率，如 `"720P"`、`"1280*720"`、`"1024*576"`
|
||||
- `watermark`: 布尔值，是否添加水印（默认 `true`）
|
||||
- `aspect_ratio`: 宽高比（如 `"16:9"`，仅部分模型支持）
|
||||
- `style`: 风格重绘中指定风格编号（0–7）
|
||||
|
||||
- **请求头（Headers）**：
|
||||
- `Authorization`: `Bearer $DASHSCOPE_API_KEY`（必填）；
|
||||
- `Content-Type`: `application/json`（必填）；
|
||||
- `X-DashScope-Async`: `enable`（必填，异步强制开关）。
|
||||
请求头必须包含：
|
||||
- `Authorization: Bearer $DASHSCOPE_API_KEY`
|
||||
- `Content-Type: application/json`
|
||||
- `X-DashScope-Async: enable`（同步调用不支持，缺失将报错）
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **准备环境**：确认模型开通地域，获取对应地域的 [API Key](https://help.aliyun.com/zh/model-studio/get-api-key)，配置为环境变量 `DASHSCOPE_API_KEY`；在控制台获取业务空间 ID（`WorkspaceId`）。
|
||||
2. **构造请求**：使用业务空间专属域名（推荐）或通用域名：
|
||||
- 专属域名（北京）：`https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis`
|
||||
- 通用域名（兼容旧模型）：`https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis`
|
||||
3. **提交任务**：发送 `POST` 请求，获取 `task_id`。
|
||||
4. **轮询结果**：使用 `GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}`（或专属域名对应路径）查询状态，直到 `status` 为 `"SUCCESS"`，响应中 `output.video_url` 即为生成视频地址。
|
||||
1. **准备环境**：
|
||||
- 在百炼控制台开通对应模型服务
|
||||
- 获取**同地域**的 API Key 并配置至环境变量 `DASHSCOPE_API_KEY`
|
||||
- 获取业务空间 ID（WorkspaceId），用于构造专属 endpoint
|
||||
|
||||
> **注意**：部分模型（如 EMO、LivePortrait、AnimateAnyone）要求严格两步流程：先调用 `detect` 模型验证输入图片合规性，再调用主模型生成视频。跳过检测将导致失败 [图生唱演视频-悦动人像EMO](../../raw/model-api-reference/video-generation-api/portrait-animation-api-reference/emo-quick-start.md)。
|
||||
2. **构造请求 URL**（以北京地域为例）：
|
||||
`POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis`
|
||||
> **注意**：旧版文档（如文档33）仍使用 `/api/v1/services/aigc/image2video/` 路径，该路径仅适用于部分 legacy 模型（如 `wan2.2-kf2v-fla`），新模型统一使用 `/video-generation/` [万相-首尾帧生视频API参考（2.2）](../../raw/model-api-reference/video-generation-api/wan-api-reference/legacy-video-models/legacy-image-to-video-by-first-and-last-frame-api-reference.md)
|
||||
|
||||
3. **提交任务**：发送 POST 请求，获取 `task_id`
|
||||
|
||||
4. **轮询结果**：使用 `GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}` 查询状态（或使用专属域名），直至 `status == "SUCCESS"`，响应中 `output.video_url` 为最终视频地址
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域一致性**：模型、Endpoint、API Key 必须同属一个地域（如华北2北京），跨地域调用必然失败。
|
||||
- **异步强制**：所有视频 API 均不支持同步调用，缺失 `X-DashScope-Async: enable` 头将返回错误 `"current user api does not support synchronous calls"`。
|
||||
- **任务生命周期**：`task_id` 有效期为 24 小时，超时后无法查询结果。
|
||||
- **并发与限流**：多数模型 QPS/RPS 限制为 1–5，同时处理中任务数上限为 1–100（依模型而异），详见各模型资费文档。
|
||||
- **输入约束**：图像需清晰、正面、单人；视频时长建议 ≤30 秒；音频需人声清晰、无背景噪音；URL 必须可公开访问且 HTTPS。
|
||||
- **废弃模型**：万相2.6 及更早版本（如 `wan2.2-s2v`、`wanx2.1-vace-plus`）已标记为 Legacy，新项目应优先选用 wan2.7 或其他新一代模型。
|
||||
- **地域强绑定**：模型、API Key、Endpoint 必须同属一个地域（如北京、新加坡、美国弗吉尼亚等），混用将导致鉴权失败或 404 错误
|
||||
- **任务生命周期**：`task_id` 有效期为 24 小时，超时后无法查询结果
|
||||
- **并发与限流**：多数模型单账号 QPS 限制为 1–5，同时处理中任务数上限为 1–100（详见各模型资费文档），超出将返回 `429 Too Many Requests`
|
||||
- **输入要求**：
|
||||
- 图像需为公网可访问 URL，格式为 JPG/PNG/WebP，尺寸建议 ≥ 512×512
|
||||
- 视频时长建议 ≤ 10 秒，格式为 MP4/MOV
|
||||
- Prompt 应简洁明确，避免冗长描述；多镜头需在 [prompt](../guides/prompt.md) 中显式说明（如“第1个镜头[0-3秒]...”），部分旧模型（如 wan2.6）需额外设置 `"prompt_extend": true`
|
||||
- **计费差异**：不同模型单价不同（如 `liveportrait` 0.02元/秒，`emo-v1` 0.08–0.16元/秒），且免费额度独立计算，调用前请确认模型计费策略
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [HappyHorse-文生视频API参考](../../raw/model-api-reference/video-generation-api/happyhorse-api-reference/happyhorse-text-to-video-api-reference.md)
|
||||
- [HappyHorse-图生视频-基于首帧API参考](../../raw/model-api-reference/video-generation-api/happyhorse-api-reference/happyhorse-image-to-video-api-reference.md)
|
||||
- [HappyHorse-参考生视频API参考](../../raw/model-api-reference/video-generation-api/happyhorse-api-reference/happyhorse-reference-to-video-api-reference.md)
|
||||
- [HappyHorse-视频编辑API参考](../../raw/model-api-reference/video-generation-api/happyhorse-api-reference/happyhorse-video-edit-api-reference.md)
|
||||
- [HappyHorse-参考生视频API参考](../../raw/model-api-reference/video-generation-api/happyhorse-api-reference/happyhorse-reference-to-video-api-reference.md)
|
||||
- [万相2.7-图生视频API参考](../../raw/model-api-reference/video-generation-api/wan-api-reference/image-to-video-general-api-reference.md)
|
||||
- [万相2.7-文生视频API参考](../../raw/model-api-reference/video-generation-api/wan-api-reference/text-to-video-api-reference.md)
|
||||
- [万相2.7-参考生视频API参考](../../raw/model-api-reference/video-generation-api/wan-api-reference/wan-video-to-video-api-reference.md)
|
||||
- [万相2.7-视频编辑API参考](../../raw/model-api-reference/video-generation-api/wan-api-reference/wan-video-editing-api-reference.md)
|
||||
- [万相2.7-参考生视频API参考](../../raw/model-api-reference/video-generation-api/wan-api-reference/wan-video-to-video-api-reference.md)
|
||||
- [万相-图生动作API参考](../../raw/model-api-reference/video-generation-api/wan-api-reference/wan-animate-move-api.md)
|
||||
- [万相-视频换人API参考](../../raw/model-api-reference/video-generation-api/wan-api-reference/wan-animate-mix-api.md)
|
||||
- [爱诗-文生视频API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-text-to-video-api-reference.md)
|
||||
- [万相-数字人](../../raw/model-api-reference/video-generation-api/wan-api-reference/wan-s2v-overview.md)
|
||||
- [图生舞蹈视频-舞动人像AnimateAnyone](../../raw/model-api-reference/video-generation-api/portrait-animation-api-reference/animateanyone-quick-start.md)
|
||||
- [爱诗-图生视频-基于首帧API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-image-to-video-api-reference.md)
|
||||
- [爱诗-参考生视频API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-reference-to-video-api-reference.md)
|
||||
- [爱诗-图生视频-基于首尾帧API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-keyframe-to-video-api-reference.md)
|
||||
- [爱诗-视频对口型API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-lipsync-api-reference.md)
|
||||
- [爱诗-视频动作模仿API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-motioncontrol-api-reference.md)
|
||||
- [爱诗-视频超清API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-upscale-api-reference.md)
|
||||
- [图生唱演视频-悦动人像EMO](../../raw/model-api-reference/video-generation-api/portrait-animation-api-reference/emo-quick-start.md)
|
||||
- [图生舞蹈视频-舞动人像AnimateAnyone](../../raw/model-api-reference/video-generation-api/portrait-animation-api-reference/animateanyone-quick-start.md)
|
||||
- [图生播报视频-灵动人像LivePortrait](../../raw/model-api-reference/video-generation-api/portrait-animation-api-reference/liveportrait-quick-start.md)
|
||||
- [视频口型替换-声动人像VideoRetalk](../../raw/model-api-reference/video-generation-api/portrait-animation-api-reference/videoretalk.md)
|
||||
- [图生表情包视频-表情包Emoji](../../raw/model-api-reference/video-generation-api/portrait-animation-api-reference/emoji-quick-start.md)
|
||||
- [视频风格重绘API参考](../../raw/model-api-reference/video-generation-api/portrait-animation-api-reference/video-style-transform-api-reference.md)
|
||||
- [视频口型替换-声动人像VideoRetalk](../../raw/model-api-reference/video-generation-api/portrait-animation-api-reference/videoretalk.md)
|
||||
- [可灵-视频生成API文档](../../raw/model-api-reference/video-generation-api/kling-api-reference/kling-video-generation-api-reference.md)
|
||||
- [爱诗-图生视频-基于首帧API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-image-to-video-api-reference.md)
|
||||
- [爱诗-文生视频API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-text-to-video-api-reference.md)
|
||||
- [爱诗-图生视频-基于首尾帧API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-keyframe-to-video-api-reference.md)
|
||||
- [HappyHorse-文生视频API参考](../../raw/model-api-reference/video-generation-api/happyhorse-api-reference/happyhorse-text-to-video-api-reference.md)
|
||||
- [爱诗-参考生视频API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-reference-to-video-api-reference.md)
|
||||
- [爱诗-视频对口型API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-lipsync-api-reference.md)
|
||||
- [爱诗-视频超清API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-upscale-api-reference.md)
|
||||
- [爱诗-视频动作模仿API参考](../../raw/model-api-reference/video-generation-api/pixverse-api-reference/pixverse-motioncontrol-api-reference.md)
|
||||
- [Vidu-文生视频API参考](../../raw/model-api-reference/video-generation-api/vidu-api-reference/vidu-text-to-video-api-reference.md)
|
||||
- [Vidu-图生视频-基于首帧API参考](../../raw/model-api-reference/video-generation-api/vidu-api-reference/vidu-image-to-video-api-reference.md)
|
||||
- [Vidu-图生视频-基于首尾帧API参考](../../raw/model-api-reference/video-generation-api/vidu-api-reference/vidu-keyframe-to-video-api-reference.md)
|
||||
- [Vidu-文生视频API参考](../../raw/model-api-reference/video-generation-api/vidu-api-reference/vidu-text-to-video-api-reference.md)
|
||||
- [Vidu-参考生视频 API 参考](../../raw/model-api-reference/video-generation-api/vidu-api-reference/vidu-reference-to-video-api-reference.md)
|
||||
- [Vidu-图生视频-基于首尾帧API参考](../../raw/model-api-reference/video-generation-api/vidu-api-reference/vidu-keyframe-to-video-api-reference.md)
|
||||
- [万相-图生视频-基于首帧API参考（2.1-2.6）](../../raw/model-api-reference/video-generation-api/wan-api-reference/legacy-video-models/legacy-image-to-video-api-reference.md)
|
||||
- [万相-文生视频API参考（2.1-2.6）](../../raw/model-api-reference/video-generation-api/wan-api-reference/legacy-video-models/legacy-wan-text-to-video-api-reference.md)
|
||||
- [万相-参考生视频API参考（2.6）](../../raw/model-api-reference/video-generation-api/wan-api-reference/legacy-video-models/legacy-wan-reference-to-video-api-reference.md)
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
# 应用构建框架对比：Managed Agents、Application Component API 与 Toolkits and Frameworks
|
||||
|
||||
## 对比目的与背景
|
||||
|
||||
在百炼平台构建 AI 原生应用时，开发者面临多种技术路径选择：从高度封装的智能体托管服务，到面向 RAG 和数据工程的原子化能力组件，再到兼容 OpenAI 协议的轻量级工具链。三者定位不同、抽象层级各异、适用阶段有别——**Managed Agents 聚焦“可交付智能体”的端到端生命周期管理；Application Component API 提供“可编排知识能力”的底层数据与检索原语；Toolkits and Frameworks 则致力于“零迁移成本”的模型调用与快速集成**。
|
||||
|
||||
本对比旨在帮助开发者基于业务目标（如是否需沙箱执行、是否依赖结构化知识库、是否已有 OpenAI 生态代码）、团队能力（如是否具备会话状态管理经验、是否熟悉 RAG 工程细节）及交付要求（如是否需版本控制、审计合规、多租户隔离），做出清晰、可落地的技术选型决策。
|
||||
|
||||
---
|
||||
|
||||
### 关键维度对比表
|
||||
|
||||
| 维度 | Managed Agents API | Application Component API | Toolkits and Frameworks |
|
||||
|------|---------------------|----------------------------|---------------------------|
|
||||
| **核心定位** | 托管式智能体运行时（Agent + Environment + Session + Skill 全栈） | 应用级数据与知识能力组件（RAG、切片、数据连接、[Prompt 工程](../concepts/prompt-engineering.md)） | OpenAI 兼容的模型调用工具链（Chat/Embedding/Vision/Batch/Conversations） |
|
||||
| **输入格式** | 事件驱动：`POST /sessions/{id}/events`，`input` 为消息数组（含 `role`, `type`, `content`，支持富媒体） | REST 请求体为主：<br>• 知识库：`CreateIndex`, `SubmitIndexJob`, `Retrieve`<br>• 文件：`AddFile`（需 `LeaseId`）<br>• 切片：`AddChunk`（JSON 结构化文本） | 标准 OpenAI Schema：<br>• `messages: [{role, content}]`（Chat）<br>• `input: string/array`（Embedding）<br>• `file` 二进制上传（Files） |
|
||||
| **输出格式** | SSE 流式事件（`message`, `session_status`, `tool_call` 等），含完整会话上下文与工具执行反馈 | JSON 响应体为主：<br>• 同步返回资源 ID（`IndexId`, `FileId`, `ChunkId`）<br>• 检索结果含 `retrieved_documents` 数组<br>• 状态查询返回 `status` 字段（如 `"FINISH"`） | OpenAI 兼容响应：<br>• Chat：`choices[0].message.content` + `usage`<br>• Embedding：`data[0].embedding`<br>• Conversations：`conversation_id`, `items[]`（含历史消息） |
|
||||
| **支持模型** | 仅百炼托管模型（当前限 `qwen-plus` 等），**不支持自定义模型 ID 或外部模型** | **不直接调用大模型**；提供 RAG 数据准备与检索能力，模型调用需配合其他接口（如 Toolkits） | 广泛支持：`qwen-plus/max/flash/long/vl-plus/ocr/coder-turbo`、`deepseek-r1`、`kimi`、`glm`、`minimax`、`text-embedding-v{1-4}` 等；**支持商业版与开源模型混用** |
|
||||
| **API 端点** | `https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio`（Region 固定 `cn-beijing`） | `https://bailian.cn-beijing.aliyuncs.com`（ROA 风格，路径含 `sfm/` 或 `bailian/2023-12-29/`） | `https://{workspace_id}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`（OpenAI 兼容路径，如 `/chat/completions`） |
|
||||
| **计费方式** | 按 **会话时长 + 工具调用次数 + 沙箱资源消耗** 计费（含环境调度开销）；文件存储按容量/时长计费 | 按 **API 调用次数 + 知识库构建时长 + 存储容量** 计费（如 `AddFile`, `SubmitIndexJob`, `Retrieve` 分别计费） | 按 **模型 [Token](../concepts/token.md) 数量（输入+输出） + 调用次数 + [文件处理](../concepts/file-processing.md)量** 计费；Batch 模式享 50% 折扣 |
|
||||
| **典型场景** | • 需沙箱执行 Python 工具的客服助手<br>• 多步骤决策型 Agent（如“分析财报→生成PPT→邮件发送”）<br>• 需严格会话隔离与技能版本控制的企业级工作流 | • 构建企业级知识库（PDF/表格/数据库接入）<br>• 细粒度文档切片与人工修正<br>• 应用数据源统一纳管（OSS/MySQL/Connector）<br>• Prompt 模板中心化管理与灰度发布 | • 快速迁移现有 OpenAI 应用（LangChain/LlamaIndex）<br>• [多模态](../concepts/multi-modal.md)理解（VL/OCR）与向量检索组合<br>• 批量离线推理（日志分析、报告生成）<br>• 跨设备长周期对话（Conversations API） |
|
||||
| **状态管理** | 内置完整会话状态机（`idle`/`running`/`terminated`），强制事件顺序与状态校验 | 无内置会话状态；知识库/文件/切片均为资源状态（如 `FINISH`/`PARSE_FAILED`），需自行维护业务状态 | Conversations API 提供会话生命周期（`create`/`get`/`update`/`append`），但无执行协调能力；其余接口无状态 |
|
||||
| **扩展性与定制** | 高：Skill 支持 ZIP 工具包上传、安全扫描、版本锁定；Environment 可配置云沙箱依赖 | 中：支持自定义解析器（`Parser`）、切片策略、连接器白名单；但不支持自定义模型或工具执行逻辑 | 低：纯模型调用层；扩展需结合 LangChain 等框架或调用其他 API（如用 Toolkits 调模型 + Managed Agents 执行工具） |
|
||||
| **安全与隔离** | 强：工具在隔离沙箱中执行（默认禁网络/宿主机访问）；File/Skill 需安全审核；工作空间级资源隔离 | 中：RAM 权限控制精细（PoLP）；知识库文件解析在服务端完成；无沙箱执行能力 | 基础：API Key 认证；模型调用无执行环境；文件上传经基础病毒扫描；依赖业务空间域名实现租户隔离 |
|
||||
|
||||
---
|
||||
|
||||
### 各方案适用场景建议
|
||||
|
||||
#### ✅ 优先选用 **Managed Agents API** 当：
|
||||
- 业务逻辑需**调用外部工具**（如查数据库、调用内部 API、运行 Python 脚本），且要求**强隔离与安全审计**；
|
||||
- 需要**完整的会话生命周期管理**（如超时自动终止、会话归档、多轮工具调用状态跟踪）；
|
||||
- 团队希望**聚焦 Agent 行为设计**（系统提示词、Skill 编排），而非底层模型调用与状态同步；
|
||||
- 项目对**版本控制、回滚、灰度发布**有硬性要求（Agent/Skill/Environment 均支持版本快照）；
|
||||
- 属于**企业级生产环境**，需满足合规审计（沙箱日志、工具执行记录、文件审核流水）。
|
||||
|
||||
#### ✅ 优先选用 **Application Component API** 当：
|
||||
- 核心需求是**构建和管理知识库**（RAG），尤其涉及非结构化文档（PDF/PPT）、结构化表格（Excel/CSV）或多源数据库接入；
|
||||
- 需要**人工干预知识加工流程**（如审核切片质量、修正错误分块、调整解析策略）；
|
||||
- 应用需**统一纳管多类数据源**（OSS、MySQL、自建 HTTP 接口），并建立元数据目录（Category）；
|
||||
- 已有成熟 [Prompt 工程](../concepts/prompt-engineering.md)体系，需**集中管理、AB 测试、灰度发布 Prompt 模板**；
|
||||
- 不涉及复杂 Agent 行为，而是将**知识检索结果作为输入，交由其他模块（如 Toolkits）进行模型生成**。
|
||||
|
||||
#### ✅ 优先选用 **Toolkits and Frameworks** 当：
|
||||
- 已有基于 **OpenAI SDK 的代码**（Python/Node.js/Java），追求**最小改造成本上线**；
|
||||
- 场景以**单次模型调用为主**（如问答、摘要、翻译、嵌入），无需多轮会话协调或工具执行；
|
||||
- 需要**快速验证多模型效果**（如对比 `qwen-max` 与 `deepseek-r1` 在特定任务的表现）；
|
||||
- 有**批量异步处理需求**（如每日 10 万条日志摘要），且能接受 Batch 模式的延迟（最高 24h）；
|
||||
- 使用 **LangChain/LlamaIndex 等框架**，希望复用现有链（Chain）、代理（Agent）或检索器（Retriever）代码。
|
||||
|
||||
---
|
||||
|
||||
### 开发者技术选型参考指南
|
||||
|
||||
| 你的问题 | 推荐方案 | 理由说明 |
|
||||
|----------|----------|----------|
|
||||
| “我需要一个能自动查订单、生成报表并邮件发送的客服助手” | ✅ Managed Agents | 唯一支持沙箱内调用订单系统 API + 生成 PPT 工具 + 邮件 SDK 的方案；会话状态确保步骤不中断。 |
|
||||
| “我要把公司 500 份产品手册建成知识库，支持员工精准检索，并允许编辑员修正切片错误” | ✅ Application Component API | 提供 `ListChunks`/`UpdateChunk`/`SubmitIndexJob` 全流程，且 `UpdateChunk` 明确支持 document 类型人工修正。 |
|
||||
| “我们已用 LangChain 开发了电商推荐 Bot，现在想切换到百炼，但不想重写所有 Chain” | ✅ Toolkits and Frameworks | `langchain_openai.ChatOpenAI` 可直接替换初始化参数（`base_url` + `api_key`），零代码修改接入 `qwen-plus`。 |
|
||||
| “我需要同时调用 Qwen-VL 看图识物 + Text-Embedding-V4 向量化 + Qwen-Max 生成文案，且三者结果要融合” | ✅ Toolkits and Frameworks | 所有接口共用 OpenAI Schema，可并行调用，响应结构一致，易于聚合处理。 |
|
||||
| “我的应用必须通过等保三级认证，要求所有工具执行留痕、沙箱隔离、文件上传二次审核” | ✅ Managed Agents | 安全审核（File/Skill）、沙箱执行、`x-request-id` 全链路追踪、工作空间级隔离均原生支持。 |
|
||||
| “我想做一个简单的 FAQ 机器人，只用知识库检索 + 模型润色回答，没有复杂逻辑” | ⚠️ 组合方案：Application Component API + Toolkits | 用 Application Component API 构建知识库并 `Retrieve`，再用 Toolkits 的 `chat.completions` 调用模型润色——发挥各自优势，避免过度设计。 |
|
||||
|
||||
> **重要提醒**：三者并非互斥，而是互补。典型生产架构常为：**Toolkits 负责模型调用 → Application Component API 提供 RAG 数据底座 → Managed Agents 封装成可交付的智能体应用**。建议从最小可行能力（MVP）切入，再按需叠加。
|
||||
|
||||
---
|
||||
*本文档依据百炼平台 2024 年 Q3 文档版本编写，具体行为请以最新 API 文档与控制台为准。*
|
||||
|
||||
## 被对比主题页
|
||||
|
||||
- [managed agents api](../api/managed-agents-api.md)
|
||||
- [application component api reference](../api/application-component-api-reference.md)
|
||||
- [toolkits and frameworks](../api/toolkits-and-frameworks.md)
|
||||
|
||||
|
||||
@@ -1,64 +0,0 @@
|
||||
# 应用编排与调用方案对比：Managed Agents vs Application Call vs Bailian Application Calling
|
||||
|
||||
为帮助开发者在百炼平台中高效选型，本文系统对比三种核心应用编排与调用方案：**Managed Agents（托管智能体运行时）**、**Application Call（应用级调用 API）** 和 **Bailian Application Calling（百炼原生应用调用）**。三者定位不同：Managed Agents 面向深度可控的智能体生命周期与沙箱环境管理；Application Call 侧重 OpenAI 兼容性与多模态[异步任务](../concepts/asynchronous-task.md)调度；Bailian Application Calling 则是百炼平台最轻量、最主流的标准化应用集成方式。本对比基于当前（2024 年 Q3）正式发布能力，聚焦技术可行性、开发成本与运维边界，不涉及未来规划或灰度功能。
|
||||
|
||||
## 关键维度对比
|
||||
|
||||
| 维度 | Managed Agents | Application Call | Bailian Application Calling |
|
||||
|------|----------------|------------------|----------------------------|
|
||||
| **定位与角色** | 智能体“运行时基础设施”：提供 Agent/Environment/Session 全生命周期托管与事件驱动交互 | “兼容层网关”：OpenAI Responses API 兼容接口，支持同步/异步/流式调用，面向迁移友好型集成 | “平台原生调用标准”：百炼官方推荐的 SDK/HTTP 调用范式，强调简洁性、一致性与[插件](../concepts/plugin.md)扩展性 |
|
||||
| **输入格式** | `POST /sessions/{id}/events`，请求体为 `input: [{role: "user", type: "message", content: "..."}]`，支持富媒体数组（含文件引用 ID） | • Responses API：`input` 字段（字符串或消息数组）<br>• DashScope API：`prompt`（单轮）或 `messages`（多轮）<br>• 支持 `input_image`、`input_file`（仅限智能体应用） | `input: {prompt: "..."}` 或 `input: {messages: [...]}`；`biz_params` 用于透传[插件](../concepts/plugin.md)参数；HTTP 请求体需严格包裹于 `input` 对象内 |
|
||||
| **输出格式** | SSE 事件流（`session_status`, `message`, `tool_call`, `error` 等），需主动订阅 `/sessions/{id}/events/stream`；响应为结构化事件对象 | • 同步：JSON 响应（含 `output.text`/`output.choices`）<br>• 异步：返回 `task_id`，需轮询 `GET /responses/{task_id}`<br>• 流式：SSE 输出 `data: {...}` | JSON 响应统一结构：`{"output": {"text": "..."}, "usage": {...}, "request_id": "...", "debug": {...}}`；支持 `debug` 字段启用执行链路详情 |
|
||||
| **支持模型** | 仅百炼托管模型：`qwen-plus` 等（通过 `model.id` 指定），**不支持自定义模型接入** | 由所调用的智能体/工作流底层模型决定；若应用配置了 `qwen-vl`，则支持图像输入；**不直接暴露模型选择权** | 同 Application Call —— 模型能力由应用发布时绑定的节点决定；调用方无需关心模型 ID，仅关注应用行为语义 |
|
||||
| **API 端点** | `https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio`（地域固定为 `cn-beijing`） | • Responses API：<br>`https://dashscope.aliyuncs.com/api/v2/apps/agent/{APP_ID}/compatible-mode/v1/responses`<br>• DashScope API：<br>`https://dashscope.aliyuncs.com/api/v1/apps/{APP_ID}/completion` | `https://dashscope.aliyuncs.com/api/v1/apps/{APP_ID}/completion`（统一 endpoint，自动路由） |
|
||||
| **会话管理** | 显式 Session 资源：创建 → 发送事件 → 订阅流 → 状态终止；会话状态机清晰（`idle → running → idle/terminated`）；历史保留 7 天 | • DashScope API：支持 `session_id`（有效期 1 小时）<br>• Responses API：**不支持会话上下文**，必须显式传入完整 `input` 消息历史 | 支持 `session_id`（1 小时有效期，最多 50 轮）；若同时提供 `messages`，**优先使用 `messages`，忽略 `session_id`** |
|
||||
| **多模态支持** | 支持文件上传（≤20 MB，经安全审核后挂载至沙箱），可作为消息内容或工具输入；**不原生支持图像输入** | ✅ 图像（`input_image`）和文件（`input_file`）均支持；文件仅限智能体应用，且需应用内配置检索模式 | ❌ **不支持图像输入**；文件需提前上传至百炼并获取 file_id，再通过 `biz_params` 或消息 content 引用（非直传） |
|
||||
| **工具/[插件](../concepts/plugin.md)集成** | 通过 Skill（zip 包）封装工具，需安全扫描、版本化挂载；工具执行由平台沙箱隔离，支持复杂工具链编排 | 工作流应用天然支持插件节点；智能体应用可通过插件配置实现；参数通过 `biz_params` 透传 | ✅ 原生支持插件参数透传：`biz_params.user_defined_params.{plugin_code}.{param_key}`；要求插件在控制台配置为“业务透传”模式 |
|
||||
| **计费方式** | 按 **Agent 运行时资源消耗** 计费（含模型调用 [Token](../concepts/token.md)、沙箱 CPU/内存、文件存储、Skill 扫描等）；费用归属工作空间 | 按 **实际调用次数与 [Token](../concepts/token.md) 消耗** 计费（同普通模型调用）；[异步任务](../concepts/asynchronous-task.md)按完成计费，不因排队等待产生费用 | 按 **应用调用次数与 [Token](../concepts/token.md) 消耗** 计费；`usage` 字段明确返回 `input_tokens`/`output_tokens` 及对应 `model_id`，便于精细化成本核算 |
|
||||
| **典型场景** | • 需要强沙箱隔离与工具执行审计的金融/政务智能体<br>• 多 Agent 协同编排（如 Planner-Executor 架构）<br>• 长周期、状态敏感的自动化流程（如数据清洗+报告生成） | • 从 OpenAI 生态平滑迁移的客户<br>• 需要异步处理长耗时任务（如视频摘要、批量文档解析）<br>• 需要流式响应但又依赖百炼工作流逻辑的前端应用 | • 快速集成客服问答、知识库检索等标准智能体<br>• 编排含多个插件调用的工作流（如“查订单→调支付→发短信”）<br>• 对 SDK 简洁性与调试信息（`debug`）有强需求的内部系统 |
|
||||
|
||||
## 各方案适用场景建议
|
||||
|
||||
- **选择 Managed Agents 当且仅当**：
|
||||
✅ 你需对智能体运行环境进行细粒度控制（如定制沙箱依赖、限制网络访问、审计工具调用日志）；
|
||||
✅ 你的业务逻辑本质是“多步骤、带状态、需人工干预或外部系统协同”的复杂工作流；
|
||||
✅ 你已构建或计划构建可复用的 Skill 工具包，并希望平台统一管理其安全扫描与版本分发；
|
||||
❌ 不适合快速原型验证、简单问答或仅需调用现成应用的场景——开发与运维成本显著更高。
|
||||
|
||||
- **选择 Application Call 当且仅当**：
|
||||
✅ 你正在将现有 OpenAI 兼容应用迁移到百炼，且希望最小化代码改造（尤其是使用 `openai` 官方 SDK 的项目）；
|
||||
✅ 你需要异步执行长耗时任务（如小时级数据处理），并接受轮询结果的编程模型；
|
||||
✅ 你的输入必须包含原始图像（如拍照识别），且已配置 VL 模型工作流；
|
||||
❌ 不适合需要稳定会话上下文的多轮对话（Responses API 不支持）、或追求百炼原生最佳实践的团队。
|
||||
|
||||
- **选择 Bailian Application Calling 当且仅当**：
|
||||
✅ 你是百炼新用户，目标是快速上线一个智能体或工作流应用到业务系统；
|
||||
✅ 你需要调用含插件的工作流，并动态传递业务参数（如订单号、用户ID）；
|
||||
✅ 你重视调用可观测性（`debug` 字段）、Token 成本透明（`usage` 结构清晰）、以及 SDK 的持续演进支持；
|
||||
❌ 不适合需要自定义模型、强沙箱隔离、或必须兼容 OpenAI `chat.completions` 接口规范的遗留系统。
|
||||
|
||||
## 技术选型参考（面向开发者）
|
||||
|
||||
| 选型考量 | 推荐方案 | 理由 |
|
||||
|----------|----------|------|
|
||||
| **首次集成百炼，追求最快上线** | ✅ Bailian Application Calling | SDK 调用一行代码即可（`Application.call()`），文档清晰，错误码统一，社区支持最完善；HTTP 接口结构简单，调试友好。 |
|
||||
| **已有 OpenAI 应用，需低成本迁移** | ✅ Application Call（Responses API） | 请求/响应格式与 OpenAI 完全一致，只需替换 endpoint 和 API Key；流式与异步能力开箱即用。 |
|
||||
| **构建企业级 AI Agent 平台，需统一管控与审计** | ✅ Managed Agents | 提供 Agent/Environment/Session 三级资源模型，支持 Skill 版本化、文件安全审核、事件溯源，符合等保与合规要求。 |
|
||||
| **调用含图像理解的工作流** | ✅ Application Call（DashScope API） | 唯一明确支持 `input_image` 参数的方案；需确保工作流已绑定 `qwen-vl` 等多模态模型。 |
|
||||
| **需要插件参数动态透传（如调用 CRM 插件传 customer_id）** | ✅ Bailian Application Calling 或 Application Call | 两者均支持 `biz_params`；但 Bailian 方案的 `biz_params.user_defined_params` 结构更规范，且控制台配置指引更明确。 |
|
||||
| **多轮对话稳定性与上下文长度要求高（>50 轮）** | ✅ Managed Agents | Session 无硬性轮次限制（仅受 Token 与超时约束），且状态机明确；另两种方案 `session_id` 最多支持 50 轮。 |
|
||||
| **预算敏感，需精确追踪各模型 Token 消耗** | ✅ Bailian Application Calling | `usage.models` 字段直接返回每个模型的 `input_tokens`/`output_tokens`，颗粒度优于其他方案。 |
|
||||
|
||||
> **重要提醒**：
|
||||
> - 所有方案均需 `DASHSCOPE_API_KEY` 鉴权，**严禁硬编码密钥**，务必使用环境变量或密钥管理服务；
|
||||
> - 地域约束以实际 endpoint 为准：Managed Agents 严格限定 `cn-beijing`；Application Call 与 Bailian Calling 默认路由至北京，但跨地域 Workspace ID 需显式传入；
|
||||
> - 文件处理能力差异显著：Managed Agents 支持上传→审核→沙箱挂载全流程；Application Call/Bailian Calling 仅支持引用已上传文件（file_id），不提供上传接口；
|
||||
> - SDK 版本至关重要：Python SDK ≥1.26.2（Managed Agents）、≥1.14.0（Bailian）、≥1.20.0（Application Call）；Java SDK 同理，请查阅各方案最新文档确认。
|
||||
|
||||
## 被对比主题页
|
||||
|
||||
- [managed agents api](../api/managed-agents-api.md)
|
||||
- [application call](../api/application-call.md)
|
||||
- [bailian application calling](../guides/bailian-application-calling.md)
|
||||
|
||||
|
||||
@@ -0,0 +1,87 @@
|
||||
# [多模态](../concepts/multi-modal.md)生成能力对比：图像生成、视频生成与3D生成
|
||||
|
||||
本文旨在为开发者提供百炼平台三大核心[多模态](../concepts/multi-modal.md)生成能力（图像生成、视频生成、3D生成）的系统性对比分析，帮助技术团队基于业务需求、性能约束、开发成本与长期演进视角，做出科学、可持续的技术选型决策。随着AIGC应用从静态内容向动态表达与空间交互延伸，理解三类能力在架构设计、调用范式、资源模型与落地边界上的差异，已成为构建高质量AI原生应用的关键前提。
|
||||
|
||||
---
|
||||
|
||||
## 关键维度对比
|
||||
|
||||
| 维度 | 图像生成 | 视频生成 | 3D生成 |
|
||||
|------|----------|----------|--------|
|
||||
| **输入格式** | 文本（`prompt`）、图像URL（图生图/局部重绘）、多图URL（参考生图，最多14张）；支持 `messages` 格式（如 `qwen-image-3.0-pro`） | 文本（T2V）、单图/首帧图/首尾帧图（I2V/KF2V）、多参考图（R2V）、视频+音频（编辑/口型同步）；`input.media` 为结构化数组，明确标注 `type`（`image_url`/`first_frame`/`video`/`audio` 等） | 文本（文生3D）、单图URL（单图生3D）、4视角图像数组（多图生3D，顺序固定为【前、左、后、右】）；三者严格互斥 |
|
||||
| **输出格式** | JPG/PNG/WEBP等标准图像文件（通过 `output.results[0].url` 返回），支持水印控制；部分模型返回多图（`n=1–9`） | MP4视频文件（`output.video_url`），含预设分辨率与时长；部分模型额外返回关键帧图或音频对齐结果 | GLB格式PBR材质3D模型（`pbr_model_url`）、无贴图基础网格（`base_model_url`）、渲染预览图（`rendered_image_url`）；所有URL有效期仅2小时 |
|
||||
| **支持模型（主力推荐）** | `wan2.6-t2i`（文生图V2）、`qwen-image-3.0-pro`（[多模态](../concepts/multi-modal.md)统一模型）、`wan2.7-image-pro`（专业编辑）、`z-image-turbo`（轻量快速） | `wan2.7-t2v-*`（T2V/I2V/KF2V三合一）、`vidu/viduq3-turbo_text2video`（高性价比）、`pixverse-c1-t2v`（通用）、`liveportrait`（数字人） | `Tripo/Tripo-H3.1`（高精度，≤200万面）、`Tripo/Tripo-P1.0`（快速交付，≤2万面）；仅限Tripo系列 |
|
||||
| **API端点（北京地域示例）** | `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`（同步/异步共用路径） | `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis`（强制异步） | `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation`（强制异步，路径名含`video-generation`属历史兼容命名） |
|
||||
| **调用模式** | **混合模式**：`wan2.6-t2i`/`z-image-turbo` 等支持**同步调用**（低延迟，<5s）；局部重绘、AI试衣等复杂任务需**异步调用**（轮询 `task_id`） | **强制异步**：所有模型均需两步调用（提交任务 → 轮询状态），`task_id` 有效期24小时；无同步选项 | **强制异步**：所有请求必须带 `X-DashScope-Async: enable`；`task_id` 有效期24小时；结果URL有效期仅2小时，需及时下载 |
|
||||
| **计费方式** | 按**成功生成的图片张数**计费（如 `wan2.6-t2i` 0.28元/张）；失败/无效输入不计费；多数模型提供500张/90天免费额度 | 按**模型+时长/任务**计费：T2V/I2V按任务单价（如 `wan2.7-t2v` 1.2元/任务），数字人按秒计费（如 `liveportrait` 0.02元/秒），超清/动作控制等附加功能单独计费；免费额度独立分配 | 按**任务成功次数**计费：`H3.1` 与 `P1.0` 单价不同（`P1.0` 更低）；无按面数/分辨率阶梯计费；免费额度有限且不跨模型共享 |
|
||||
| **典型场景** | 社媒配图、电商主图生成、设计稿初稿、AI绘画创作、证件照美化、商品背景替换、创意文字艺术 | 短视频营销（文生视频）、产品演示动画（图生视频）、虚拟主播播报（数字人）、广告片剪辑辅助（视频编辑）、AR内容前置制作（口型同步） | 电商3D商品建模（单图转3D）、工业零件快速原型（多图重建）、游戏资产生成（文生低模）、元宇宙空间构件（PBR材质模型） |
|
||||
| **地域约束** | 支持华北2（北京）、新加坡、美国（弗吉尼亚）等多地域；**Key/Endpoint/WorkspaceId 必须同地域** | 同图像生成，严格地域绑定；跨地域调用返回鉴权失败或404 | **仅支持华北2（北京）地域**；其他地域Endpoint不可用，API Key必须为北京地域生成 |
|
||||
| **输入限制** | 图像：JPG/PNG/WEBP/BMP/AVIF；尺寸 ≥512×512 且 ≤4096×4096；单图 ≤10MB | 图像：JPG/PNG/WebP，≥512×512；视频：MP4/MOV，≤10秒；Prompt建议简洁明确 | 图像：JPEG/PNG；宽高 ∈ [20, 6000]px；单图 ≤20MB；`input.images` 数组长度**必须为4**（空视角填 `{}`） |
|
||||
| **输出限制** | 分辨率范围广：`wan2.6-t2i` 支持1280×1280至1440×1440；`qwen-image-3.0-pro` 支持512×512至2048×2048 | 时长：主流3–5秒，部分模型支持最长10秒；分辨率：720P/1024×576等常见规格；宽高比支持有限（如`16:9`需模型显式支持） | 模型面数：`P1.0` ≤2万面，`H3.1` ≤200万面（`ultra`模式）；`geometry_quality` 参数仅 `H3.1` 有效 |
|
||||
|
||||
---
|
||||
|
||||
## 各方案适用场景建议
|
||||
|
||||
### ✅ 图像生成 —— 适合「高频、轻量、确定性输出」场景
|
||||
- **推荐场景**：内容运营批量配图、电商SKU主图自动化、UI设计灵感草图、个性化头像/海报生成、A/B测试素材生产。
|
||||
- **选型建议**：
|
||||
- 追求**极致响应速度** → 选用 `z-image-turbo` 或 `wan2.6-t2i`（同步调用）；
|
||||
- 需要**强语义理解与图文协同** → 优先 `qwen-image-3.0-pro`（支持T2I+I2I+多图输入）；
|
||||
- 涉及**专业图像编辑**（如换背景、修人像、风格迁移）→ 使用 `wan2.7-image-pro` 或 `qwen-image-edit`；
|
||||
- **避免使用**已标注“仅免费体验”的模型（如 `wanx-x-painting`, `shoemodel-v1`），长期项目应迁移到主力模型。
|
||||
|
||||
### ✅ 视频生成 —— 适合「动态表达、人机交互、轻量三维叙事」场景
|
||||
- **推荐场景**：短视频平台AI内容生产、企业宣传动画、教育课程可视化、虚拟数字人直播、电商产品动态展示、社交App滤镜特效。
|
||||
- **选型建议**：
|
||||
- **通用文生/图生视频** → `wan2.7-t2v-*`（功能整合度高，维护活跃）或 `viduq3-turbo`（性价比优）；
|
||||
- **需要数字人播报** → `liveportrait`（低成本）或 `emo-v1`（高表现力）；
|
||||
- **精准口型/动作控制** → `pixverse-lipsync` + `pixverse-motioncontrol` 组合调用；
|
||||
- **规避风险**：勿使用 `wan2.2` 等旧版模型（路径 `/image2video/` 已逐步淘汰），新项目一律采用 `/video-generation/` 路径。
|
||||
|
||||
### ✅ 3D生成 —— 适合「空间建模、工业可视化、元宇宙资产构建」场景
|
||||
- **推荐场景**：电商3D商品页快速搭建、工业设计原型验证、游戏低模资产生成、AR/VR内容预生产、建筑可视化构件补充。
|
||||
- **选型建议**：
|
||||
- **追求交付速度与成本可控** → 首选 `Tripo/Tripo-P1.0`（2万面足够展示级应用，生成快、单价低）；
|
||||
- **需要高精度几何与PBR材质**（如用于渲染器导入、3D打印预览）→ 使用 `Tripo-H3.1` 并启用 `geometry_quality: "ultra"`；
|
||||
- **严格注意**：必须部署在北京地域服务集群；多图输入务必保证4视角数组完整性（即使缺视角也需占位 `{}`）；结果URL需在2小时内完成下载与持久化存储。
|
||||
|
||||
---
|
||||
|
||||
## 面向开发者的选型参考指南
|
||||
|
||||
1. **优先评估调用链路复杂度**
|
||||
- 若业务要求**毫秒级响应**（如实时设计工具插件），图像生成中的同步模型是唯一选择；视频与3D生成因强制异步，天然不适合低延迟场景。
|
||||
- 若已具备异步任务调度能力（如Celery/K8s Job），三者均可纳入架构，但需为视频/3D额外设计结果缓存与过期刷新机制。
|
||||
|
||||
2. **关注长期维护性与模型演进路径**
|
||||
- 百炼平台明确将 `wan2.7` 系列（图像/视频）、`qwen-image-3.0-pro`、`Tripo-P1.0/H3.1` 定位为主力持续迭代模型；
|
||||
- `wanx-v1`、`wan2.5` 及更早版本、`wan2.2` 视频模型等已被标注“推荐替代”，应避免新项目接入。
|
||||
|
||||
3. **成本精细化管控要点**
|
||||
- 图像：按张计费，`n=1` 与 `n=4` 成本线性增长，需结合业务实际需求数量配置；
|
||||
- 视频：数字人按秒计费，务必控制生成时长；视频编辑类任务可能产生多次调用，需预估完整工作流成本；
|
||||
- 3D：`H3.1` 的 `ultra` 模式虽提升质量，但显著增加耗时与失败率，建议先用 `standard` 验证效果再升级。
|
||||
|
||||
4. **地域与基础设施协同设计**
|
||||
- 若应用部署在新加坡，**不可调用北京地域的3D API**；需统一规划模型服务地域，避免跨域Key混用导致鉴权失败；
|
||||
- 建议为不同模态能力申请独立WorkspaceId，便于配额隔离、监控告警与权限管理。
|
||||
|
||||
5. **错误处理与可观测性增强**
|
||||
- 所有异步任务（视频/3D及部分图像）必须实现健壮的轮询逻辑（含退避重试、超时熔断）；
|
||||
- 推荐启用百炼平台的[异步回调](https://help.aliyun.com/zh/model-studio/async-task-api)功能，替代高频轮询，降低服务压力；
|
||||
- 对输入URL做预检（HTTP HEAD + MIME类型校验），避免因图片不可访问导致任务失败却无法定位根因。
|
||||
|
||||
> 📌 **总结一句话选型原则**：
|
||||
> **图像生成 = 快速产出确定性视觉内容；视频生成 = 构建动态叙事与人格化交互；3D生成 = 构建可交互的空间实体资产。三者非替代关系，而是AIGC能力栈中逐层递进、面向不同抽象层级的基础设施。**
|
||||
|
||||
---
|
||||
*最后更新：2024年6月 | 百炼平台技术文档组*
|
||||
|
||||
## 被对比主题页
|
||||
|
||||
- [image generation](../api/image-generation.md)
|
||||
- [video generation api](../api/video-generation-api.md)
|
||||
- [3d generation](../api/3d-generation.md)
|
||||
|
||||
|
||||
@@ -1,74 +0,0 @@
|
||||
# 多模态生成能力对比：Image Generation vs Video Generation API vs 3D Generation
|
||||
|
||||
本页面旨在为开发者提供百炼平台三大核心多模态生成能力的系统性对比，涵盖图像生成（Image Generation）、视频生成（Video Generation API）与三维模型生成（3D Generation）在技术架构、使用方式、能力边界及工程实践层面的关键差异。随着AIGC应用场景从静态内容向动态表达与空间交互演进，准确理解各模态生成服务的定位、约束与协同潜力，是构建高质量AI原生应用（如电商可视化、数字人内容工厂、游戏资产管线、工业设计辅助等）的技术前提。
|
||||
|
||||
---
|
||||
|
||||
## 关键维度对比
|
||||
|
||||
| 维度 | Image Generation | Video Generation API | 3D Generation |
|
||||
|------|------------------|----------------------|----------------|
|
||||
| **核心任务类型** | 文生图（T2I）、图生图（I2I）、图像编辑（局部重绘/擦除/扩图/风格迁移等） | 文生视频（T2V）、图生视频（I2V）、首尾帧生成、参考生视频（R2V）、数字人驱动、口型同步、视频后处理（超分/风格重绘） | 文生3D、单图生3D、四视角多图生3D（前/左/后/右） |
|
||||
| **输入格式** | • 文本提示（`prompt` 或 `messages[].content[].text`）<br>• 图像URL（支持最多14张参考图，含 `mask_image_url` 用于局部操作）<br>• 混合文本+图像输入（如 `vidu/vidu-image_reference2image`） | • 纯文本（`input.prompt`）<br>• 单图/多图URL（`media` 数组，支持 `first_frame`/`last_frame`/`reference_image` 等类型）<br>• 音频URL（数字人场景需 `audio_url` + `image_url`）<br>• 视频URL（部分编辑模型） | • 纯文本（`input.prompt`）<br>• 单图URL（`input.image`）<br>• 四元素数组（`input.images`，按「前-左-后-右」顺序，空视角用 `{}` 占位）<br>• **三者互斥，不可混用** |
|
||||
| **输出格式** | • Base64 编码图像（同步调用）<br>• 公网可访问 URL（异步调用，有效期24小时）<br>• 支持 JPG/PNG/WEBP/BMP 格式 | • 视频 URL（MP4/H.264，有效期24小时）<br>• 预览图 URL（`output.preview_url`，WebP，部分模型）<br>• 元数据（时长、分辨率、帧率等） | • PBR材质模型 URL（GLB格式，含贴图，`pbr_model_url`，有效期2小时）<br>• 无贴图基础网格 URL（`base_model_url`，需显式配置）<br>• 渲染预览图 URL（WebP，`rendered_image_url`，有效期2小时） |
|
||||
| **支持模型（典型代表）** | `wan2.6-t2i`, `qwen-image-3.0-pro`, `kling/kling-v3-image-generation`, `wanx-x-painting`, `shoemodel-v1` 等（共20+专用模型） | `wan2.7-t2v`, `pixverse/pixverse-c1-t2v`, `vidu/viduq3-turbo_text2video`, `emo`, `liveportrait`, `animateanyone` 等（覆盖生成+驱动+后处理） | `Tripo/Tripo-H3.1`（高精度，≤200万面），`Tripo/Tripo-P1.0`（快速，≤2万面） |
|
||||
| **API 调用模式** | • **同步 & 异步双模支持**：<br> ✓ `wan2.6-t2i`/`qwen-image-3.0-pro` 等新协议模型支持同步返回<br> ✗ `wanx-sketch-to-image-lite`/`wanx-x-painting` 等强制异步 | • **强制异步**：<br> 所有模型均需 `X-DashScope-Async: enable`，两步流程（提交任务 → 轮询 `task_id`）<br> `task_id` 有效期24小时 | • **强制异步**：<br> 必须携带 `X-DashScope-Async: enable`<br> `task_id` 有效期24小时，结果资源（URL）仅保留2小时 |
|
||||
| **地域支持** | • 华北2（北京）、新加坡、美国（弗吉尼亚）<br>• **地域隔离严格**：API Key、Endpoint、Workspace ID 必须同地域 | • 华北2（北京）、新加坡、美国（弗吉尼亚）<br>• **地域强绑定**：模型开通、API Key、Endpoint URL 必须完全一致，跨地域调用必失败 | • **仅限华北2（北京）**：<br> 控制台入口、API Key、Endpoint 均锁定北京地域<br> 其他地域调用直接报错，无降级或兼容路径 |
|
||||
| **计费方式** | • 按生成图片张数计费（如 1 张 = 1 [Token](../concepts/token.md)）<br>• 多数模型提供 **500 张/90天免费额度**<br>• 部分垂直模型（如 `wanx-x-painting`）**额度用尽即停用，不支持付费续订** | • 按视频生成任务计费（1次成功任务 = 1 [Token](../concepts/token.md)）<br>• 按分辨率/时长/模型等级分级定价（如 `720P` vs `4K`，3s vs 5s）<br>• 免费额度较少（通常 10–50 次/月），**全部支持付费扩容** | • 按任务成功次数计费（1次 = 1 [Token](../concepts/token.md)）<br>• `H3.1`（高面数）单价高于 `P1.0`（快速版）<br>• **无公开免费额度**，需预充值或开通后按量扣费 |
|
||||
| **典型场景** | • 电商商品图生成与背景替换<br>• 社媒配图/营销海报批量制作<br>• UI设计稿转真实效果图<br>• 人像精修与风格化（试穿/重绘）<br>• 涂鸦→成品图（Sketch-to-Image） | • 短视频内容自动化生产（广告/教程/资讯）<br>• 数字人播报/虚拟主播驱动<br>• 产品演示动画（图→3s动态展示）<br>• 口型同步配音（VideoRetalk）<br>• 动作复刻（AnimateAnyone） | • 工业/消费电子产品3D建模（文生/图生）<br>• 游戏资产快速原型（角色/道具）<br>• AR/VR内容管线接入（GLB直输引擎）<br>• 电商3D商品展示（替代传统摄影） |
|
||||
|
||||
---
|
||||
|
||||
## 各方案适用场景建议
|
||||
|
||||
### ✅ 选择 Image Generation 当：
|
||||
- 需要**高吞吐、低延迟**交付静态视觉内容（如每日千张营销图）；
|
||||
- 任务以**精细编辑**为核心（局部重绘、去水印、超分、风格迁移）；
|
||||
- 输入源为**文本描述或单张参考图**，且无需时间维度表达；
|
||||
- 对**成本敏感**，可充分利用免费额度（500张/90天）；
|
||||
- 开发团队偏好**同步调用简化逻辑**（推荐 `qwen-image-3.0-pro` 或 `z-image-turbo`）。
|
||||
|
||||
### ✅ 选择 Video Generation API 当：
|
||||
- 应用需**动态叙事能力**（如短视频脚本→成片、产品功能演示动画）；
|
||||
- 涉及**人物驱动类需求**（数字人播报、唱演、口型同步、动作模仿）；
|
||||
- 输入具备**多模态组合特征**（图+文+音，或首帧+末帧+提示词）；
|
||||
- 接受**异步工作流**并已集成轮询/回调机制；
|
||||
- 场景对**时长（3–5秒）与画质（720P–4K）有明确分级要求**，且预算支持按质付费。
|
||||
|
||||
### ✅ 选择 3D Generation 当：
|
||||
- 目标是生成**可导入Unity/Unreal/Blender的标准化3D资产**（GLB with PBR）；
|
||||
- 输入为**结构化视角图像**（四视图）或**精确文本描述**（如“不锈钢圆柱形保温杯，带硅胶防滑环”）；
|
||||
- 业务链路需**与CAD/AR/电商平台深度集成**（如自动生成SKU 3D模型）；
|
||||
- **仅在北京地域部署服务**，且能接受2小时资源有效期（需及时下载）；
|
||||
- 对模型面数有明确分级需求：`P1.0`（快速验证） vs `H3.1`（生产级精度）。
|
||||
|
||||
---
|
||||
|
||||
## 技术选型参考（面向开发者）
|
||||
|
||||
| 选型关注点 | 推荐方案 | 关键依据 |
|
||||
|------------|----------|----------|
|
||||
| **开发效率优先** | Image Generation（同步模式） | 单次HTTP请求即得Base64，无轮询/状态管理开销；SDK封装成熟（DashScope Python/Java） |
|
||||
| **跨地域部署需求** | Image Generation 或 Video Generation API | 二者均支持北京/新加坡/美东三地；3D Generation 仅限北京，若需全球服务需额外架构适配 |
|
||||
| **输入灵活性最高** | Video Generation API | 支持文本+图像+音频+视频多模态混合输入，且 `media` 字段类型丰富（`first_frame`/`reference_image`/`audio_url`） |
|
||||
| **输出可集成性最强** | 3D Generation | 原生输出标准GLB（含PBR材质），零改造对接主流渲染引擎与3D平台；Image/Video 输出需额外解码/转码 |
|
||||
| **成本可控性最佳** | Image Generation | 免费额度覆盖中小规模应用；Video/3D均为纯按量计费，无缓冲期 |
|
||||
| **长周期任务稳定性** | Video Generation API 或 3D Generation | 二者均强制异步，`task_id` 24小时有效，适合后台批处理；Image Generation 的[异步任务](../concepts/asynchronous-task.md)同样24小时，但同步模式无此保障 |
|
||||
| **未来扩展性考量** | Video Generation API | 生态最活跃（持续新增数字人/动作模型），且与Image Generation存在天然协同（如“先图生图→再图生视频”流水线） |
|
||||
|
||||
> **重要提醒**：
|
||||
> - 所有服务均**强依赖地域一致性**——务必校验 API Key、Workspace ID、Endpoint 三者地域标签完全匹配；
|
||||
> - **[异步任务](../concepts/asynchronous-task.md)务必实现幂等轮询或启用回调通知**（[异步任务回调文档](https://help.aliyun.com/zh/model-studio/async-task-api)），避免因网络抖动丢失结果；
|
||||
> - 图像/视频/3D 的输入URL必须**公网可访问、HTTPS、无鉴权**；内网OSS链接需生成临时公链；
|
||||
> - 3D模型生成对输入图像质量敏感，**多图生3D强烈建议使用专业四视图拍摄**，非正交视角将显著降低重建精度。
|
||||
|
||||
---
|
||||
*最后更新：2024年6月 | 百炼平台技术文档中心*
|
||||
|
||||
## 被对比主题页
|
||||
|
||||
- [image generation](../api/image-generation.md)
|
||||
- [video generation api](../api/video-generation-api.md)
|
||||
- [3d generation](../api/3d-generation.md)
|
||||
|
||||
|
||||
@@ -1,62 +0,0 @@
|
||||
# 知识能力方案对比：Knowledge API vs Knowledge Base
|
||||
|
||||
为帮助开发者在百炼平台中高效构建 RAG（[检索增强生成](../concepts/rag.md)）应用，本文对两种核心知识能力方案——**Knowledge API**（应用层知识服务接口）与**Knowledge Base**（底层知识库基础设施）进行系统性对比分析。二者定位不同：Knowledge API 是面向业务快速集成的「开箱即用型」RAG 服务，而 Knowledge Base 是面向深度定制的「可配置、可扩展」知识底座。理解其差异是技术选型、架构设计与成本优化的关键前提。
|
||||
|
||||
---
|
||||
|
||||
## 关键维度对比
|
||||
|
||||
| 维度 | Knowledge API | Knowledge Base |
|
||||
|------|----------------|----------------|
|
||||
| **定位与抽象层级** | 应用网关层封装的高阶服务，屏蔽底层细节，提供标准化 RAG 能力入口 | 平台级基础设施能力，提供知识建模、存储、检索、重排、生成全链路控制权 |
|
||||
| **输入格式** | 纯文本 `query`（支持多轮上下文需自行维护）；`top_k` 仅用于 `/search` 接口 | 多模态原始数据（PDF/DOCX/图片/音视频/表格等）+ 配置化元数据 + 检索参数（相似度阈值、TopK、标签过滤等） |
|
||||
| **输出格式** | • `/search`：JSON 格式结构化切片列表（含 `content`, `score`, `metadata`）<br>• `/chat`：SSE 流式响应，分阶段返回 `planning` → `tool_calling` → `generation` 事件 | • 检索接口：JSON 切片列表（含重排后 `relevance_score`、`chunk_id`、`source_file` 等）<br>• 问答接口：支持流式/非流式，返回结构化答案 + 引用溯源（含文件名、页码、时间戳等） |
|
||||
| **支持模型** | **不开放模型选择**：由平台统一调度（默认 Qwen 系列大模型），用户不可指定或切换 | **完全开放模型选择**：<br>• 预置模型：Qwen3/Qwen2.5/Qwen2/Long/Max/Plus/Turbo/Coder/Deep-Research/VL 系列等<br>• 第三方模型：DeepSeek-R1/V3.1、Llama3.1、Yi-Large、abab6.5s 等<br>• 自定义微调模型（基于上述基座） |
|
||||
| **API 端点** | • 检索：`POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search`<br>• 问答：`POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/knowledge/chat` | • 知识库管理：`POST /api/v1/knowledge_bases`（创建/删除/查询）<br>• 文件上传：`POST /api/v1/knowledge_bases/{kb_id}/files`<br>• 检索：`POST /api/v1/knowledge_bases/{kb_id}/retrieve`<br>• 问答：`POST /api/v1/knowledge_bases/{kb_id}/chat`<br>（完整端点详见 [知识库 API 指南](https://help.aliyun.com/zh/model-studio/rag-knowledge-base-api-guide)） |
|
||||
| **计费方式** | • **按调用量计费**：以 QPS 和请求次数为核心计量单元<br>• 无知识库规格费、无向量存储费、无 Rerank 单独费用<br>• 仅产生模型 [Token](../concepts/token.md) 费用（隐式包含在 API 调用中） | • **双重计费**：<br> ✓ 规格费用（按小时）：标准版（固定）或旗舰版（RCU 可调，1 RCU ≈ 50 QPS）<br> ✓ 模型调用费用（按 [Token](../concepts/token.md)）：检索、重排（Rerank）、生成各阶段独立计费<br>• Rerank 费用取决于**初步召回总切片数**（非最终返回数），可显著影响成本 |
|
||||
| **典型场景** | • 快速验证 RAG 效果（MVP 阶段）<br>• 无需知识库运维的轻量级问答服务（如客服 FAQ 助手）<br>• 与已有业务系统通过 HTTP 快速对接，无复杂依赖 | • 垂直领域深度知识增强（如金融研报分析、医疗文献问答）<br>• 多模态混合检索（图文并茂、音视频剧情理解）<br>• 需精细控制检索策略（Query 改写、混合检索、标签过滤、元数据驱动）<br>• 构建智能体（Agent）工作流中的知识节点 |
|
||||
| **部署与运维要求** | • **零部署**：无需创建/发布知识库，仅需已发布的 `app_id`（对应知识应用）<br>• `app_id` 必须处于“运行中”状态，否则返回 `404` | • **需主动创建与配置**：包括知识库类型、解析策略、元数据抽取规则、重排模型等<br>• 支持控制台可视化操作 + 全量 API 管理<br>• 创建后关键配置（类型/元数据/多轮改写）**不可修改**，需谨慎规划 |
|
||||
| **地域支持** | 与业务空间（`workspaceId`）所在地域一致，**不限定北京地域** | **仅限华北2（北京）地域**，其他地域（如新加坡、法兰克福）暂不支持 |
|
||||
| **扩展性与定制性** | 低：功能边界由平台固化（如不支持自定义切片、无法关闭 Rerank、无 NL2SQL） | 高：支持自定义切片编辑、多库路由、NL2SQL、视觉理解、ASR 帧提取、日志监控（SLS）、SSE/非流式双模式 |
|
||||
|
||||
---
|
||||
|
||||
## 适用场景建议
|
||||
|
||||
### ✅ 选择 **Knowledge API** 当：
|
||||
- 项目处于原型验证（PoC）或敏捷上线阶段，追求「分钟级接入」；
|
||||
- 业务逻辑简单，仅需基础语义检索或单轮问答，无需多模态、多轮上下文补全或结构化过滤；
|
||||
- 团队无 RAG 运维经验，希望规避向量引擎、切片策略、重排模型等底层复杂性；
|
||||
- 已有成熟知识应用（`app_id`），只需通过标准 HTTP 接口调用其能力；
|
||||
- 对成本敏感且 QPS 较低（≤25），可接受平台统一模型调度带来的效果上限。
|
||||
|
||||
### ✅ 选择 **Knowledge Base** 当：
|
||||
- 需要处理 PDF 图表、扫描件 OCR、会议视频、产品手册等**多模态私有数据**；
|
||||
- 要求**精准可控的知识召回**：例如按部门标签过滤合同、按日期范围筛选财报、按文件类型区分 SOP 与培训材料；
|
||||
- 构建 Agent 工作流，需将知识库作为可编排节点（支持权重调节、提示词注入 `{result}`、失败重试策略）；
|
||||
- 需深度优化 RAG 效果：通过调整 `相似度阈值`、`初步 TopK`、启用 `Query 改写` 或 `知识库路由` 提升准确率；
|
||||
- 有长期知识资产沉淀需求，需版本管理、审计日志（SLS）、权限隔离（子账号策略）及高可用规格（旗舰版 RCU 弹性伸缩）。
|
||||
|
||||
---
|
||||
|
||||
## 技术选型参考（面向开发者）
|
||||
|
||||
| 决策维度 | 推荐动作 |
|
||||
|----------|----------|
|
||||
| **起步阶段（1–2 周 MVP）** | 优先使用 Knowledge API：创建知识应用 → 发布 → 调用 `/chat` 接口验证效果。避免过早投入知识库配置与调试。 |
|
||||
| **生产环境（稳定、可维护、可扩展）** | 迁移至 Knowledge Base：利用其多模态支持、精细参数控制与日志监控能力，构建可持续演进的 RAG 架构。 |
|
||||
| **混合架构（兼顾效率与灵活性）** | 将 Knowledge API 用于通用问答入口（如官网 FAQ），Knowledge Base 用于高价值垂直场景（如销售知识助手、法务合规审查），通过业务路由分发请求。 |
|
||||
| **成本敏感型项目** | • Knowledge API：关注 QPS 限流（25 QPS），合理设计客户端退避重试；<br>• Knowledge Base：关闭 Rerank 或调低 `初步向量检索 TopK`（如设为 20），启用免费额度抵扣规格费。 |
|
||||
| **安全与合规要求高** | Knowledge Base 更优：支持子账号最小权限（`AliyunBailianDataFullAccess`）、知识库级数据隔离、删除不可逆（符合 GDPR 数据擦除要求）。 |
|
||||
| **未来演进考量** | Knowledge Base 是百炼 RAG 能力演进主航道：新特性（如多知识库协同推理、动态切片更新、私有向量模型部署）均优先落地于此。Knowledge API 作为简化入口，长期保持稳定但功能迭代较保守。 |
|
||||
|
||||
> 💡 **一句话总结**：
|
||||
> **Knowledge API 是「RAG 的快捷方式」，Knowledge Base 是「RAG 的操作系统」**。
|
||||
> 快速上手选前者，长期深耕选后者；两者并非互斥，而是百炼平台 RAG 能力栈中互补的两层——上层封装易用性，底层释放专业性。
|
||||
|
||||
## 被对比主题页
|
||||
|
||||
- [knowledge](../api/knowledge.md)
|
||||
- [knowledge base](../guides/knowledge-base.md)
|
||||
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
# [长期记忆](../concepts/long-term-memory.md)方案对比：Long Term Memory 与 Memory Library
|
||||
|
||||
## 对比目的与背景
|
||||
|
||||
在百炼平台智能体开发实践中，“[长期记忆](../concepts/long-term-memory.md)”是构建具备上下文感知、用户理解与持续交互能力的关键基础设施。当前平台存在两套命名相近、功能重叠但定位差异显著的[长期记忆](../concepts/long-term-memory.md)能力：**Long Term Memory（新）**（文档标识为 `long-term-memory-new`）与 **Memory Library**（文档标识为 `memory-library-overview`）。开发者常因名称混淆、接口相似、文档分散而难以准确选型，导致集成成本上升、能力误用或架构冗余。
|
||||
|
||||
本文旨在系统性对比二者在技术实现、能力边界、使用范式与运维特性上的核心差异，为开发者提供清晰、可落地的技术选型参考，避免“用错能力、多走弯路”。
|
||||
|
||||
> ⚠️ 重要说明：
|
||||
> - **二者并非版本迭代关系**（即 Memory Library 不是 Long Term Memory 的旧版），而是面向不同抽象层级与使用场景的并行能力组件；
|
||||
> - **Memory Library 是平台级能力总称与产品概念**，而 **Long Term Memory（新）是其底层核心 API 实现之一**，但 Memory Library 还包含画像管理、OpenClaw 插件集成、多应用共享等更高阶能力；
|
||||
> - 所有对比均基于当前（2024年Q3）百炼平台正式发布的文档与 API 行为，不涉及内测或灰度功能。
|
||||
|
||||
---
|
||||
|
||||
## 关键维度对比表
|
||||
|
||||
| 维度 | Long Term Memory（新） | Memory Library |
|
||||
|------|------------------------|----------------|
|
||||
| **本质定位** | **轻量级、API 优先的记忆操作能力封装**，聚焦单点记忆片段的增删改查与语义检索 | **平台级长期记忆解决方案**，涵盖记忆片段、用户画像、插件集成、多应用协同等完整能力栈 |
|
||||
| **输入格式** | • 必须传入 `messages`（最多50条）或 `custom_content`（≤512字符）<br>• `messages.content` 支持 string/array（含 image_url），但仅文本参与解析 | • 同样支持 `messages` / `custom_content` 输入<br>• **额外支持 `profile_schema` 触发结构化画像抽取**<br>• `meta_data` 字段更标准化，明确用于业务分类与上下文标记 |
|
||||
| **输出格式** | • `AddMemory` 返回 `memory_node_id` 及基础元数据（`created_at`, `score` 等）<br>• `SearchMemory` 返回带 `score` 的记忆片段数组，结构较扁平 | • 输出与 Long Term Memory 兼容（同构响应体）<br>• **额外提供 `GetUserProfile` 等专属接口，返回结构化 JSON 画像对象**<br>• `ListMemory` 支持分页与 `status` 字段（如 `active`/`archived`） |
|
||||
| **支持模型** | • 依赖百炼统一专用记忆模型（非通用大模型）<br>• **不开放模型选择权**，所有能力由平台自动调度 | • 同样基于专用记忆模型<br>• **通过 `project_id` 可显式绑定不同记忆规则（含不同模型微调版本或提取策略）**，支持 A/B 测试与策略灰度 |
|
||||
| **API 端点** | • 固定 Base URL：<br>`https://dashscope.aliyuncs.com/api/v2/apps/memory/`<br>• 接口路径严格遵循 `/add`, `/search`, `/list`, `/delete`, `/update` | • **端点完全兼容 Long Term Memory（同一 Base URL）**<br>• **额外提供画像专属端点**：<br>`/profile/schema`（创建 Schema）<br>`/profile/{user_id}`（获取画像）<br>`/library/{id}/rules`（管理规则） |
|
||||
| **计费方式** | • 按 API 调用量计费（QPS/月调用量）<br>• `AddMemory`、`SearchMemory` 等独立计费项<br>• **无按存储容量或记忆条目数收费** | • 计费模型与 Long Term Memory **完全一致**（同一计费体系）<br>• **但 `GetUserProfile` 等画像接口计入独立计费单元**，需注意配额分配 |
|
||||
| **典型场景** | • 快速接入单点记忆能力（如聊天机器人待办提醒）<br>• 需要细粒度控制每条记忆生命周期（如手动 `UpdateMemory`）<br>• 对 SDK 封装要求高（如 `agentscope-runtime` 异步工具链） | • 构建完整用户理解闭环（记忆 + 画像 + 动态召回）<br>• 多 Agent / 多应用共享同一记忆源（如客服+营销系统共用用户偏好）<br>• 通过 OpenClaw 插件实现零代码自动捕获与召回 |
|
||||
| **SDK 支持** | • Python SDK (`agentscope-runtime>=1.1.5`) 提供 `AddMemory`, `SearchMemory`, `ListMemory` 封装<br>• `UpdateMemory` 和 `DeleteMemory` **需手写 HTTP 请求**（文档明确提示） | • 官方推荐使用 `dashscope` SDK 或 `agentscope`<br>• **OpenClaw 插件提供 `memory_store`, `memory_search` 等开箱即用工具函数**，支持 Agent 运行时直接调用<br>• `CreateProfileSchema`, `GetUserProfile` 均有完整 SDK 封装 |
|
||||
| **扩展能力** | • 支持 `enable_rerank`/`enable_judge`/`enable_rewrite` 等高级搜索开关（需显式启用）<br>• 仅支持默认记忆库或显式指定 `memory_library_id` | • **支持多记忆库管理（创建/编辑/切换）**<br>• **支持记忆规则（`project_id`）配置过期策略、字段映射、敏感词过滤等**<br>• 提供控制台可视化管理界面（记忆库列表、规则配置、画像 Schema 编辑） |
|
||||
|
||||
---
|
||||
|
||||
## 适用场景建议
|
||||
|
||||
### ✅ 推荐选用 **Long Term Memory（新）** 当：
|
||||
- 项目处于快速原型验证阶段，只需基础记忆存取与语义搜索；
|
||||
- 已有成熟 Agent 框架（如 AgentScope），且希望最小侵入式集成；
|
||||
- 开发者熟悉 REST API 调用，能接受部分操作（如更新、删除）需手写请求；
|
||||
- 场景对用户画像无强需求，仅需事件型记忆（如“会议提醒”、“订单备注”）；
|
||||
- 需要精细控制 `SearchMemory` 的重排（rerank）、相关性判断（judge）等高级搜索行为。
|
||||
|
||||
### ✅ 推荐选用 **Memory Library** 当：
|
||||
- 构建生产级智能体应用，需同时管理**记忆片段 + 结构化用户画像**（如金融KYC、电商个性化推荐）；
|
||||
- 存在多个子系统或 Agent（如客服Bot、营销Bot、IoT控制Agent），需**跨应用共享同一用户记忆源**；
|
||||
- 希望通过 **OpenClaw 插件实现全自动记忆捕获（autoCapture）与动态召回（autoRecall）**，降低开发复杂度；
|
||||
- 需要**可视化配置记忆规则**（如设置某类记忆180天后自动归档）、**管理多套画像 Schema** 或进行 A/B 策略实验；
|
||||
- 团队具备一定平台使用经验，愿意利用控制台进行记忆库治理与监控。
|
||||
|
||||
> 💡 **混合使用建议**：
|
||||
> 在大型项目中，常见模式是：
|
||||
> - 使用 **Memory Library 的 `AddMemory` / `SearchMemory` 接口**（享受插件与画像能力）；
|
||||
> - 对于需要极致性能或特殊搜索策略的模块，**单独调用 Long Term Memory（新）的 `SearchMemory` 并启用 `enable_rerank`**；
|
||||
> - **始终通过 `user_id` 隔离数据空间**，确保两种能力写入的数据可被对方检索（因底层存储同源）。
|
||||
|
||||
---
|
||||
|
||||
## 技术选型决策指南（面向开发者）
|
||||
|
||||
| 决策问题 | 推荐答案 | 依据说明 |
|
||||
|----------|----------|----------|
|
||||
| **我只需要记住用户说过的话，并在下次对话中召回——该选哪个？** | Long Term Memory（新）即可满足 | 功能精简、接入快、无额外学习成本；Memory Library 的优势在此场景未被激活 |
|
||||
| **我的 Agent 需要从对话中自动提取“年龄=28”、“职业=设计师”等字段，并持久化为结构化数据——必须用哪个？** | 必须选用 Memory Library | Long Term Memory（新）不提供 `CreateProfileSchema` 或 `GetUserProfile` 接口，无法完成画像闭环 |
|
||||
| **我有 5 个不同业务线的 Bot，希望它们共用同一套用户偏好记忆——如何设计？** | 使用 Memory Library，为所有 Bot 配置相同 `memory_library_id` | Long Term Memory（新）虽支持 `memory_library_id`，但缺乏多库管理、权限隔离与控制台视图，运维风险高 |
|
||||
| **我正在用 OpenClaw 开发 Agent，不想写任何记忆 API 调用代码——怎么选？** | 直接启用 Memory Library 的 OpenClaw 插件 | Long Term Memory（新）无官方插件支持，需自行封装 `autoCapture` 逻辑 |
|
||||
| **我担心 API 调用出错，需要完整的错误追踪与问题排查能力——哪个更友好？** | 两者均返回 `request_id`，但 Memory Library 文档中明确强调 `request_id` 用于工单提报与日志关联，实操支持更完善 | Long Term Memory（新）文档仅提及 `request_id`，未说明其在售后支持中的具体用途 |
|
||||
|
||||
> 📌 **最后提醒**：
|
||||
> - **不要重复创建记忆库**：Memory Library 的“默认记忆库”已预置可用，Long Term Memory（新）若不传 `memory_library_id` 即使用该库；
|
||||
> - **务必校验 `user_id`**：两个方案均强制要求，缺失将直接返回 400 错误；
|
||||
> - **关注限流策略**：两者共享同一账号级 QPM 配额（总计 ≤3000 QPM），需在整体架构中统一分配；
|
||||
> - **数据一致性有保障**：写入 Long Term Memory（新）的数据，可被 Memory Library 的 `SearchMemory` 检索到，反之亦然——二者底层存储与索引服务统一。
|
||||
|
||||
## 被对比主题页
|
||||
|
||||
- [long term memory new](../api/long-term-memory-new.md)
|
||||
- [memory library overview](../guides/memory-library-overview.md)
|
||||
|
||||
|
||||
@@ -1,61 +1,75 @@
|
||||
# 模型部署方式对比：Model Production vs Model Deployment 1
|
||||
# 模型部署方式对比：Model Deployment、Model Production 与 Fine-tuning
|
||||
|
||||
本文旨在帮助开发者清晰区分百炼平台中两种核心模型服务化能力——`Model Production`（模型生产）与 `Model Deployment 1`（模型部署 1），明确其定位、能力边界与适用阶段。二者虽均面向“将模型变为可用 API 服务”，但设计目标、抽象层级、资源模型与运维责任存在本质差异：
|
||||
- **Model Production** 是**模型生命周期编排层**，聚焦“从训练成果到可调用服务”的端到端自动化流程，强调微调与部署的强耦合、统一管控与快速验证；
|
||||
- **Model Deployment 1** 是**生产级推理服务交付层**，聚焦“已就绪模型在高负载、多 SLA 场景下的稳定、可控、可计量运行”，强调性能隔离、计费精细化与企业级运维保障。
|
||||
正确理解二者关系（非互斥，而是演进关系），是构建稳健 AI 应用的关键前提。
|
||||
为帮助开发者在百炼平台上高效、合规地将大模型投入实际业务，本文系统对比三种核心能力：**Model Deployment（模型部署）**、**Model Production（模型生产）** 与 **Fine-tuning（微调）**。三者并非并列选项，而是构成「定制→发布→服务化」完整链路的关键环节：
|
||||
- **Fine-tuning** 聚焦**模型能力定制**（如何让模型更懂你的业务）；
|
||||
- **Model Production** 提供**端到端生命周期管理**（训练→验证→版本→部署的自动化流水线）；
|
||||
- **Model Deployment** 专注**生产级服务交付**（如何稳定、低成本、低延迟地对外提供推理能力）。
|
||||
|
||||
理解其定位差异、能力边界与协同关系，是技术选型、架构设计与成本优化的前提。
|
||||
|
||||
---
|
||||
|
||||
## 关键维度对比
|
||||
|
||||
| 维度 | Model Production | Model Deployment 1 |
|
||||
|------|------------------|----------------------|
|
||||
| **核心定位** | 模型生产流水线：统一管理微调任务 + 部署服务，实现“训完即用” | 生产级推理服务交付：为已就绪模型提供资源独占、SLA 可控、计费灵活的专属服务 |
|
||||
| **输入格式** | • 微调：标注数据集 ID（`training_file_id`）+ 基座模型名（如 `qwen2-7b`）<br>• 部署：已完成微调/导入的模型 ID（`model_id`） | • 预置模型：标准模型名（如 `qwen-flash-2025-07-28`）<br>• 调优模型：SFT/LoRA 模型 ID（如 `qwen3-8b-ft-20251113...`）<br>• 导入模型：OSS 路径 + LoRA 模型约束校验通过的 `adapter_model.safetensors` 等文件 |
|
||||
| **输出格式** | • 微调输出：`model_id`（唯一标识新模型版本）<br>• 部署输出：全局唯一 `endpoint_url`（如 `https://my-llm-v1.bailian.aliyuncs.com/v1/chat/completions`） | • 所有模式均输出标准 DashScope/OpenAI 兼容 API 端点（如 `https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation`），通过 `model_name`（部署服务名）路由请求 |
|
||||
| **支持模型类型** | • 仅支持百炼平台内完成的 SFT 微调模型<br>• 支持通过 [模型导入](../../raw/model-api-reference/model-production/deployments-api.md) 上传的完整权重模型（但**不可用于微调**）<br>• 不支持 LoRA、多模态、RLHF 模型 | • **预置模型**：Qwen / DeepSeek / GLM / Qwen-VL 全系列（含 Flash/Plus/VL 等变体）<br>• **调优模型**：平台内 SFT/LoRA 微调产出的模型 ID<br>• **导入模型**：仅限符合约束的 LoRA 模型（rank ∈ {8,16,32,64}，VIT 冻结，chat_template 未修改） |
|
||||
| **API 端点** | • 微调：`POST /v1/fine_tuning_jobs`<br>• 部署：`POST /v1/deployments`<br>• 推理：`POST {endpoint_url}/v1/chat/completions`（专属域名） | • 部署：DashScope API `POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/deployments`<br>• 推理：`POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation`（通用域名，按 `model_name` 路由） |
|
||||
| **计费方式** | • **统一按实例规格 + 运行时长计费**：<br> - 微调任务：GPU 实例小时费 × 实际运行时长（≤72h）<br> - 部署服务：GPU 实例小时费 × 在线时长（自动扩缩容，min=1/max=5）<br>• 无 PTU/MU/[Token](../concepts/token.md) 等分层计费概念 | • **三类独立计费模式**：<br> - **PTU（预置吞吐）**：预购输入/输出 token 分钟额度，超限可选自动溢出或限流<br> - **MU（模型单元）**：按模型单元规格（如 MU1 x 8）后付费，支持 PD 分离、Thinking 模式、RPM/TPM 限流<br> - **[Token](../concepts/token.md) 计费（LoRA 专属）**：按实际请求 token 数量计费，仅限导入 LoRA 模型 |
|
||||
| **资源调度与隔离** | • 自动扩缩容（默认 min=1, max=5），共享资源池<br>• 无物理/逻辑资源独占保障，适合开发测试与中小流量场景 | • **全模式资源独占**：<br> - PTU：逻辑吞吐隔离，共享底层 GPU，但配额硬保障<br> - MU：物理 GPU 卡级隔离（如 MU1 = 1×A10），完全独占<br> - [Token](../concepts/token.md)：共享资源池，但按 token 精确计量，无资源预留 |
|
||||
| **典型场景** | • 快速验证微调效果（训完立刻部署试跑）<br>• 内部工具链集成（CI/CD 中自动触发微调→部署→测试）<br>• 小规模 PoC 或 MVP 应用，流量波动大、SLA 要求不高 | • 面向终端用户的高并发应用（如客服机器人、内容生成平台）<br>• 对首 Token 延迟、稳定性、上下文长度有严苛要求的业务（如实时对话、长文档摘要）<br>• 需要精细成本控制与预算规划的企业级部署（PTU 预算锁定 / MU 性能保障 / LoRA 效果验证） |
|
||||
| 维度 | Model Deployment（模型部署） | Model Production（模型生产） | Fine-tuning（微调） |
|
||||
|------|------------------------------|------------------------------|------------------------|
|
||||
| **本质定位** | **在线推理服务交付层**：将已存在模型（预置/微调/导入）封装为高可用 API 服务 | **模型全生命周期管理层**：覆盖微调训练、版本控制、灰度发布与标准化部署的统一工作流 | **模型能力定制层**：基于自有数据对基座模型进行参数更新，提升领域适配性 |
|
||||
| **输入格式** | - PTU/MU：模型 ID（如 `qwen3.7-plus-2026-05-26`）<br>- LoRA：LoRA 模型 ID（如 `qwen3-8b-ft-abc123`） | - 微调任务：`base_model` + `training_file_id`（JSONL）<br>- 部署任务：`model_version_id`（来自微调产出） | - 文本：ChatML 格式 JSONL（`{"messages": [...]}`）<br>- 视觉：ZIP 包（含 `data.jsonl` + 图片/视频）<br>- 语音：ZIP 包（WAV 音频 + 元数据） |
|
||||
| **输出格式** | 统一 OpenAI 兼容 REST API 响应（`choices[0].message.content`），支持流式（`stream: true`） | - 微调产出：`model_version_id`（唯一版本标识）<br>- 部署产出：`endpoint_url` + `deployment_name`（服务标识） | - 训练产物：`finetuned_output`（模型路径/ID）<br>- 支持导出为 SafeTensors 或 Hugging Face 格式（部分场景需人工审核） |
|
||||
| **支持模型** | - PTU：`glm-5.1`, `deepseek-v4-pro`, `qwen3.7-plus-2026-05-26`（长输入优化）<br>- MU：全量千问/GLM/DeepSeek/千问VL/CosyVoice 系列<br>- LoRA：仅限微调生成的 `*-ft-*` 模型 | - 微调：`qwen2-7b/57b`, `llama3-8b`, `qwen3-*` 等平台预置基座模型（**不支持自定义基座**）<br>- 部署：所有微调产出模型 + 通过 `import_model` 导入的 HF 格式模型 | - 文本：`qwen3-8b`, `qwen3.5-9b`, `qwen3-vl-8b-instruct` 等（SFT/CPT/DPO/RL）<br>- 视觉：`wan2.7-image-pro`, `wan2.7-i2v` 等<br>- 语音：`cosyvoice-v3-flash`（API 专属）<br>- RL：`qwen3.5-9b` 等 MoE/非 MoE 模型 |
|
||||
| **API 端点** | `POST /api/v1/deployments`（`plan: "ptu"` / `"mu"` / `"lora"`） | - 微调：`POST /fine_tuning/jobs`<br>- 部署：`POST /deployments`（独立于 Model Deployment 的 API） | - 文件上传：`POST /files`（`purpose="fine-tune"`）<br>- 任务创建：`POST /api/v1/fine-tunes`（文本/视觉）或 `AgenticRL.run()`（RL） |
|
||||
| **计费方式** | - PTU：预付费吞吐额度（KTPM/月），溢出可选自动转按量<br>- MU：按模型单元时长（MU·小时）计费<br>- LoRA：按 [Token](../concepts/token.md) 用量（输入+输出）计费 | - 微调：按训练消耗 [Token](../concepts/token.md) 数计费（文本/视觉）或 MTU 单元（RL）<br>- 部署：继承底层 Model Deployment 计费模式（即部署时需选择 PTU/MU/lora） | - SFT/CPT/DPO：按训练 [Token](../concepts/token.md) 总数 × epoch 数计费<br>- CosyVoice：0.2 元/千 Token（训练）+ MU 时长（部署）<br>- RL：强制使用 MTU 训练单元（预/后付费） |
|
||||
| **典型场景** | - 高并发客服机器人（PTU）<br>- 私有化金融风控系统（MU，需思考模式+RPM限流）<br>- A/B 测试轻量模型（LoRA 按量调用） | - 快速迭代 FAQ 知识库（微调 → 版本 → 灰度发布）<br>- 多团队共享同一基座模型的不同业务分支（版本隔离）<br>- 自动化 CI/CD 流水线集成模型上线 | - 客服话术风格迁移（SFT）<br>- 行业术语理解增强（CPT）<br>- 图像生成品牌风格定制（SFT-LoRA）<br>- Agent 工具调用能力强化（RL） |
|
||||
|
||||
## 各方案适用场景建议
|
||||
> ⚠️ **关键协同说明**：
|
||||
> - Fine-tuning 产出的模型（如 `qwen3-8b-ft-xxx`）**必须通过 Model Deployment 或 Model Production 的部署接口发布为服务**，不可直接调用；
|
||||
> - Model Production 的 `/deployments` 接口本质是 Model Deployment 能力的封装，但**不支持 PTU/MU 的精细化配置**（如前缀缓存、`enable_thinking`、`max_context_length`），若需这些能力，应直接使用 Model Deployment API；
|
||||
> - `qwen3.7-plus-2026-05-26` 等长上下文模型在 PTU 模式下享受阶梯系数优惠，但在 Model Production 部署流程中**无法启用该优化**，需优先选用 Model Deployment。
|
||||
|
||||
### ✅ 推荐使用 **Model Production** 当：
|
||||
- 你正在**迭代优化模型**，需要频繁执行“微调 → 验证 → 调参 → 再微调”闭环；
|
||||
- 你的工作流高度依赖**自动化编排**（例如 GitHub Actions 触发微调、成功后自动部署到测试环境）；
|
||||
- 应用处于**早期验证阶段**，流量低且不稳定，无需承诺 SLA 或精确成本控制；
|
||||
- 你使用的是**完整权重微调模型**，且不涉及 LoRA、视觉语言等复杂架构。
|
||||
---
|
||||
|
||||
> ⚠️ 注意：若需长期稳定服务、高并发或定制化性能策略（如 PD 分离、Thinking 模式），不应止步于 Model Production，应将其产出的 `model_id` 作为输入，迁移到 Model Deployment 1。
|
||||
## 适用场景建议
|
||||
|
||||
### ✅ 推荐使用 **Model Deployment 1** 当：
|
||||
- 模型已**完成调优并进入生产发布阶段**，需提供稳定、可计量、可运维的服务；
|
||||
- 业务对**延迟（P99 < 500ms）、吞吐（≥1000 RPM）、上下文长度（≥128K）** 有明确 SLA 要求；
|
||||
- 需要**精细化成本治理**：如用 PTU 锁定月度预算、用 MU 保障关键业务性能、用 Token 模式低成本验证多个 LoRA 方案；
|
||||
- 部署模型为**LoRA 适配器**（尤其是 OSS 导入场景），或需利用前缀缓存、长输入优化等高级推理特性；
|
||||
- 需要**企业级管控能力**：如 RPM/TPM 限流、自定义推理模式（Instruct/Thinking）、跨模型灰度发布。
|
||||
### ✅ 选择 **Model Deployment** 当：
|
||||
- 你已有**成熟模型**（平台预置模型、LoRA 微调产物、OSS 导入模型），需立即上线高 SLA 服务；
|
||||
- 业务对**延迟、吞吐、资源隔离**有强要求（如实时交易风控、高并发对话引擎）；
|
||||
- 需要**精细化性能调控**：启用思考模式、设置最大上下文长度、配置 RPM/TPM 限流、利用前缀缓存降低长输入成本；
|
||||
- 运维团队具备 API/命令行操作能力，追求部署灵活性与成本可控性。
|
||||
|
||||
> ⚠️ 注意：Model Deployment 1 **不提供微调能力**。若需微调，必须先通过 Model Production 完成训练，再将产出的 `model_id` 作为 `model_name` 输入 Model Deployment 1 进行部署。
|
||||
### ✅ 选择 **Model Production** 当：
|
||||
- 你处于**模型迭代期**，需频繁执行「微调 → 验证 → 发布」闭环，且重视**版本追溯与灰度能力**；
|
||||
- 团队采用 DevOps 实践，希望将模型上线纳入**标准化 CI/CD 流水线**（如 GitHub Actions 触发微调+部署）；
|
||||
- 业务方无需关心底层资源规格，只需关注 `model_version_id` 和 `deployment_name` 等语义化标识；
|
||||
- 使用场景**不涉及 PTU 缓存、MU 独占等高级特性**，接受通用 GPU 实例部署。
|
||||
|
||||
### ✅ 选择 **Fine-tuning** 当：
|
||||
- 通用大模型在你的业务场景（如医疗问答、法律文书生成、品牌视觉风格）**效果未达预期**；
|
||||
- 你拥有**高质量、领域专属的标注数据**（≥1k 条高质量样本），且能保障数据安全与合规；
|
||||
- 需要**深度定制模型行为**：调整输出风格、注入专业知识、优化偏好对齐（DPO）、增强工具调用能力（RL）；
|
||||
- 接受训练耗时（数小时至数天）与迭代周期，以换取长期效果收益。
|
||||
|
||||
---
|
||||
|
||||
## 技术选型参考（面向开发者）
|
||||
|
||||
| 你的需求 | 推荐方案 | 关键理由 | 行动指引 |
|
||||
|----------|-----------|-----------|-----------|
|
||||
| “我刚微调完一个 Qwen2-7B 模型，想立刻让同事试用一下效果” | ✅ Model Production | 一键部署，5 分钟内获得专属 endpoint，无需配置计费与规格 | 调用 `POST /v1/deployments`，传入微调任务返回的 `model_id` |
|
||||
| “我的客服系统日均 5000 请求，要求首 Token < 800ms，P95 延迟 < 2s” | ✅ Model Deployment 1（MU 模式） | MU 提供物理 GPU 隔离与 PD 分离计算，可精准控制延迟与并发 | 控制台选择 `MU2 x 4` 规格，启用 `enable_thinking: false`，设置 `rpm_limit: 100` |
|
||||
| “我要上线一个内容生成 SaaS，需按客户用量精确计费，且支持突发流量” | ✅ Model Deployment 1（PTU 模式） | PTU 提供吞吐硬保障 + 自动溢出机制，兼顾成本确定性与弹性 | 预购 `input_tpm: 50000, output_tpm: 5000`，溢出策略设为 `auto_overflow` |
|
||||
| “我有多个 LoRA 方案（不同 [prompt](../guides/prompt.md) 工程/领域适配），想低成本批量验证效果” | ✅ Model Deployment 1（Token 计费模式） | 仅对实际 token 收费，无资源预留成本，适合 A/B 测试与快速淘汰 | 使用 `plan: "lora"` 部署各 LoRA 模型 ID，监控 token 消耗与效果指标 |
|
||||
| “我需要把本地训练的 LoRA 模型（rank=32）部署到百炼，且保持 VIT 冻结” | ✅ Model Deployment 1（LoRA 导入 + Token 计费） | 唯一支持 OSS LoRA 导入的路径，且严格校验 rank/VIT 约束 | 按 [模型导入](../../raw/model-user-guide/model-deployment-1/model-import.md) 文档准备文件，部署时指定 `plan: "lora"` |
|
||||
| “我需要在微调过程中实时查看 loss 曲线，并自动保存最佳 checkpoint” | ❌ 两者均不直接支持 | Model Production 仅提供日志与最终 model_id；Model Deployment 1 不涉及训练 | 需结合百炼 [训练作业日志](../../raw/model-api-reference/model-production/fine-tuning-jobs-api.md) + 自定义 callback 或外部监控 |
|
||||
| 你的需求 | 推荐方案 | 关键动作 | 注意事项 |
|
||||
|----------|----------|----------|----------|
|
||||
| **“我有个微调好的 LoRA 模型，想快速上线测试”** | Model Deployment（`plan: "lora"`） | 控制台选择模型 → 设 `plan=lora` → 提交 → 获取 `deployed_model` 名称调用 | • 仅支持 LoRA 模型<br>• 不支持扩缩容（需人工审核）<br>• 成本按 Token 实时结算 |
|
||||
| **“我要部署一个千问 VL [多模态](../concepts/multi-modal.md)模型，要求最低 200ms P99 延迟，且需开启思考模式”** | Model Deployment（`plan: "mu"`） | API 提交 `{"plan":"mu", "deploy_spec":"MU2", "enable_thinking":true, "max_context_length":131072}` | • MU 是唯一支持 `enable_thinking` 的模式<br>• `max_context_length` 需模型本身支持<br>• 地域限制：仅华北2（北京） |
|
||||
| **“我们每周更新一次客服知识库，需要自动微调+灰度发布”** | Model Production | 1. 上传新数据 → 2. `POST /fine_tuning/jobs` → 3. 监听 `succeeded` → 4. `POST /deployments`（指定新 `model_version_id`）→ 5. 切流量 | • 微调与部署使用不同 API 域名<br>• 部署后 `endpoint_url` 可直接用于业务调用<br>• 灰度需配合网关路由实现 |
|
||||
| **“我想用公司财报 PDF 微调一个金融分析模型”** | Fine-tuning（SFT） | 1. 提取 PDF → 构建 ChatML JSONL（含 `system` + `user` + `assistant`）→ 2. ZIP 打包 → 3. 上传 → 4. 创建 `efficient_sft` 任务 | • 推荐 `lora_rank=16`, `n_epochs=3`<br>• 避免在 `messages` 中插入原始 PDF 内容（token 超限）<br>• 训练后务必在小样本上验证逻辑一致性 |
|
||||
| **“我的应用需要 10K QPS，且输入平均 8K token，预算敏感”** | Model Deployment（PTU） | 1. 计算所需 `input_tpm`（例：10K QPS × 8K token × 60 ≈ 4.8M TPM → 选 5000 KTPM）→ 2. 开启「自动溢出」→ 3. 启用前缀缓存 | • PTU 是长输入场景唯一经济方案<br>• 必须显式配置 `ptu_capacity.input_tpm`<br>• 溢出策略影响服务稳定性，需监控 `x-dashscope-ptu-overflow` 响应头 |
|
||||
|
||||
> 💡 **最佳实践组合**：
|
||||
> **开发期** → 使用 `Model Production` 快速迭代微调与轻量部署；
|
||||
> **发布期** → 将验证通过的 `model_id` 输入 `Model Deployment 1`，按业务 SLA 选择 PTU/MU/Token 模式部署；
|
||||
> **运维期** → 通过 Model Deployment 1 的控制台/API 统一管理扩缩容、限流、计费账单，Model Production 仅用于后续版本迭代。
|
||||
> 💡 **终极建议**：
|
||||
> - **先微调，再部署**：Fine-tuning 是价值起点，Model Deployment 是效能终点；
|
||||
> - **生产环境首选 Model Deployment**：它提供最细粒度的性能、成本与稳定性控制；
|
||||
> - **避免混用 Model Production 部署 + PTU/MU 配置**：二者 API 能力不重叠，强行组合将丢失关键特性；
|
||||
> - **始终以控制台实时可选列表为准**：文档列举的模型 ID 可能滞后，创建前务必验证兼容性。
|
||||
|
||||
## 被对比主题页
|
||||
|
||||
- [model production](../api/model-production.md)
|
||||
- [model deployment 1](../guides/model-deployment-1.md)
|
||||
- [model production](../api/model-production.md)
|
||||
- [fine tuning](../guides/fine-tuning.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,77 +1,70 @@
|
||||
# 实时 API 方案对比：Realtime API vs Omni Realtime API
|
||||
# 实时 API 方案对比：Omni Realtime API vs Realtime API
|
||||
|
||||
## 对比目的与背景
|
||||
本文旨在帮助开发者清晰区分百炼平台两大实时交互能力——**Omni Realtime API** 与 **Realtime API（广义协议栈）**，明确其定位差异、能力边界与适用约束。二者虽均面向低延迟[多模态](../concepts/multi-modal.md)交互场景，但设计哲学、架构层级与使用范式存在本质区别：
|
||||
- **Omni Realtime API** 是一个**具体、统一的 WebSocket 接口规范**，聚焦于 `qwen-omni-*` 系列模型的端到端实时对话能力，强调事件驱动、细粒度流控与语音/文本/图像协同；
|
||||
- **Realtime API** 是一个**协议抽象层与接入框架**，提供 AOQ、WebRTC、WebSocket 三种传输通道，支持更广泛的模型类型（含 Omni 全模态、ASR、TTS、翻译等），强调跨平台兼容性、弱网鲁棒性与媒体栈可定制性。
|
||||
|
||||
为帮助开发者在百炼平台上高效选型，本文系统对比两种主流实时交互方案：**Realtime API**（多协议统一架构）与 **Omni Realtime API**（WebSocket 专用增强接口）。二者均面向低延迟、多模态 AI 交互场景，但设计目标、能力边界与集成路径存在显著差异。
|
||||
|
||||
- **Realtime API** 是平台级实时能力底座，通过 AOQ / WebRTC / WebSocket 三协议分层支持，强调**跨端兼容性、弱网鲁棒性与协议灵活性**，适用于对传输质量、端侧生态或服务端可控性有差异化要求的中大型业务。
|
||||
- **Omni Realtime API** 是基于 WebSocket 的垂直优化接口，聚焦**对话体验深度控制**（如 VAD 精细调参、工具链闭环、搜索/[函数调用](../concepts/function-calling.md)），面向需要高自由度会话编排、快速原型验证或轻量级 Web/服务端集成的开发者。
|
||||
|
||||
本对比不替代具体模型文档，而是从工程落地视角提供技术选型决策依据。
|
||||
正确理解二者关系是技术选型的前提：**Omni Realtime API 是 Realtime API 协议体系下、专为 Omni 模型优化的 WebSocket 实现子集；而 Realtime API 本身不限于 Omni 模型，也不限于 WebSocket 协议。**
|
||||
|
||||
---
|
||||
|
||||
## 关键维度对比表
|
||||
## 关键维度对比
|
||||
|
||||
| 维度 | Realtime API | Omni Realtime API |
|
||||
|------|--------------|-------------------|
|
||||
| **核心定位** | 多协议统一实时交互底座（协议即能力） | WebSocket 原生增强型多模态对话接口（功能即能力） |
|
||||
| **支持协议** | ✅ AOQ（移动端原生）、✅ WebRTC（浏览器/WebApp）、✅ WebSocket（服务端/通用） | ❌ 仅 WebSocket（无 AOQ/WebRTC 支持） |
|
||||
| **输入格式** | - 音频：16 kHz PCM（`input_audio_format="pcm"`）<br>- 视频：H.264/H.265 编码流（AOQ/WebRTC）<br>- 文本：`session.update` 中 `input_text` 字段（部分模型） | - 音频：16 kHz PCM（Base64 编码，`input_audio_buffer.append`）<br>- 图像：JPG/JPEG（≤1080p，Base64 ≤256KB，`input_image_buffer.append`）<br>- 文本：不支持直接文本输入（需转音频或图像） |
|
||||
| **输出格式** | - 文本：`response.text.delta` / `response.text.done`<br>- 音频：24 kHz PCM（`modalities=["text","audio"]`）<br>- 视频：H.264/H.265 解码帧（AOQ/WebRTC） | - 文本：`conversation.item.text.delta` / `conversation.item.text.done`<br>- 音频：24 kHz PCM（`modalities=["text","audio"]`）<br>- **不支持视频输出** |
|
||||
| **支持模型** | - 全模态：`qwen3.5-omni-plus-realtime`、`qwen3.5-omni-flash-realtime`、`qwen3.5-livetranslate-flash-realtime`<br>- 单模态：`Fun-ASR`、`CosyVoice`、`qwen-audio-3.0-realtime-plus/flash`（**仅 WebSocket**）<br>- 多模态套件：`multimodal-dialog`（**仅 WebRTC/WebSocket**，AOQ 不支持） | - 全模态：`qwen3.5-omni-realtime`（最强能力）、`qwen3-omni-flash-realtime`、`qwen-omni-turbo-realtime`<br>- 内置 ASR：`qwen3-asr-flash-realtime`（增量转录）<br>- **不支持单模态独立模型（如 Fun-ASR/CosyVoice）** |
|
||||
| **API 端点** | - AOQ：`https://dashscope.aliyuncs.com/api/v1/realtime/allocate`（鉴权） + 客户端直连 relay endpoint<br>- WebRTC：白名单专属 STUN/TURN + 信令 endpoint（需商务开通）<br>- WebSocket：`wss://dashscope.aliyuncs.com/api-ws/v1/realtime` | - 统一 WebSocket endpoint：<br>`wss://{WorkspaceId}.{Region}.maas.aliyuncs.com/api-ws/v1/realtime`（按工作空间地域路由） |
|
||||
| **计费方式** | 按 **实际调用时长（秒）+ 输出 token 数 + 输入 token 数** 计费<br>不同协议、不同模型单价独立（AOQ/WebRTC 通常略高于 WebSocket） | 按 **实际调用时长（秒）+ 输出 token 数 + 输入 token 数** 计费<br>与 Realtime API 同源计费体系，但 `qwen3.5-omni-realtime` 等高级模型单价更高 |
|
||||
| **VAD 能力** | - `semantic_vad`：支持（推荐用于 `qwen3.5-omni-*` 系列）<br>- `server_vad`：部分模型支持（需确认服务端兼容性）<br>- 客户端 VAD：需自行实现并触发 `input_audio_buffer.commit` | - `semantic_vad`：仅 `qwen3.5-omni-realtime` 支持<br>- `server_vad`：全系列支持，可配 `silence_duration_ms` / `idle_timeout_ms`<br>- Manual 模式：完全由客户端控制 `commit` 时机 |
|
||||
| **高级功能** | - 工具调用：✅（`qwen3.5-omni-*` 系列）<br>- 联网搜索：❌（当前未开放）<br>- 自定义采样参数：✅（`temperature`/`top_p` 等，依模型而定） | - 工具调用：✅（`qwen3.5-omni-realtime`，需 `tools` 配置）<br>- 联网搜索：✅（`enable_search=true`，与 `tools` 互斥）<br>- 自定义采样参数：✅（`qwen3.5-omni-realtime`），❌（`turbo` 系列不可调） |
|
||||
| **开发门槛** | - AOQ：需集成 SDK + Opus [插件](../concepts/plugin.md) + 服务端 [Token](../concepts/token.md) 分发，移动端适配成本高<br>- WebRTC：需处理 SDP 协商、ICE 连接、媒体轨道管理，浏览器兼容性需验证<br>- WebSocket：最低门槛，类 HTTP 接入 | - WebSocket 原生协议，事件驱动清晰（`session.created` → `session.update` → `input_audio_buffer.append` → `response.done`）<br>- 提供 Java/Python SDK 封装，开箱即用 |
|
||||
| **弱网对抗能力** | - AOQ：QUIC 底层，内置丢包重传、拥塞控制、前向纠错（FEC）<br>- WebRTC：内置 NACK/PLI/FIR、带宽自适应（ABR）<br>- WebSocket：无原生弱网优化，依赖 TCP 重传 | - 依赖 WebSocket 底层（TCP），无协议级弱网优化<br>- 依赖客户端实现重连、缓冲、降质保连等策略 |
|
||||
| **安全要求** | - AOQ：**严禁客户端硬编码 API Key**，必须使用服务端下发的临时 `aoqTokenForClient`<br>- WebRTC/WebSocket：API Key 可直连，但仍建议服务端代理鉴权 | - API Key 直连 WebSocket，**强烈建议通过服务端代理中转连接**（避免 Key 泄露） |
|
||||
| 维度 | Omni Realtime API | Realtime API（广义协议栈） |
|
||||
|------|-------------------|-----------------------------|
|
||||
| **本质定位** | 面向 `qwen-omni-*` 模型的**标准化 WebSocket 接口规范**（单一协议、固定事件模型） | **多协议实时通信框架**，包含 AOQ（移动端原生）、WebRTC（浏览器/跨平台）、WebSocket（服务端/原型）三套接入路径 |
|
||||
| **输入格式** | - PCM 音频（16 kHz，单声道）<br>- JPG/JPEG 图像（≤1080p，Base64 编码 ≤256 KB）<br>- 文本（通过 `session.update` 或 `input_text` 事件） | - PCM 音频（16 kHz）<br>- 视频帧（I420/NV12/BGRA/JPEG，AOQ/WebRTC 支持）<br>- 文本（各协议均支持）<br>- *不支持图像输入（除 Omni 模型在 WebSocket 路径下）* |
|
||||
| **输出格式** | - `["text"]` 或 `["text","audio"]`（音频为 24 kHz PCM）<br>- 严格按事件流推送：`response.text.delta`、`response.audio.delta`、`response.audio_transcript.delta` 等 | - 输出模态由 `modalities` 决定（如 `["text","audio"]`）<br>- 协议决定交付形式：<br> ✓ AOQ/WebRTC：音频/文本混合流（含同步时间戳）<br> ✓ WebSocket：纯事件流（类似 Omni） |
|
||||
| **支持模型** | **仅限 `qwen-omni-*` 系列**：<br>- `qwen3.5-omni-realtime`（plus/flash）<br>- `qwen3-omni-flash-realtime`<br>- `qwen-omni-turbo-realtime` | **全模型谱系支持**：<br>- ✅ Omni 全模态模型（三协议均支持）<br>- ✅ 实时语音识别（Fun-ASR，仅 WebSocket）<br>- ✅ 实时语音合成（CosyVoice，仅 WebSocket）<br>- ✅ 实时语音对话（qwen-audio-3.0，仅 WebSocket）<br>- ✅ [多模态](../concepts/multi-modal.md)开发套件（multimodal-dialog，仅 WebRTC/WebSocket）<br>- ❌ 不支持非实时模型（如 standard Qwen3） |
|
||||
| **API 端点** | 固定 WebSocket 地址：<br>`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime`<br>（需替换 `{WorkspaceId}`） | **协议差异化端点**：<br>- AOQ：通过网关获取 Relay 接入点（`relayEndpoints`）+ `aoqTokenForClient`<br>- WebRTC：信令服务器地址 + SDP 交换流程<br>- WebSocket：同 Omni 端点（但鉴权方式不同） |
|
||||
| **计费方式** | 按 **实际调用时长（秒） + 输出 token 数 + 输出音频时长（秒）** 分项计费<br>（Omni 模型专属计费模型，含 VAD、工具调用等附加能力） | 按 **所选模型 + 协议 + 使用资源** 计费：<br>- Omni 模型：同 Omni Realtime API 计费规则<br>- Fun-ASR/CosyVoice：按音频处理时长（秒）计费<br>- multimodal-dialog：按会话时长 + 调用次数计费<br>※ 各协议无额外传输费用 |
|
||||
| **典型场景** | - 高互动性语音助手（需语义 VAD、主动引导、工具调用）<br>- 智能客服坐席系统（需音色复刻、多轮上下文保持）<br>- 实时[多模态](../concepts/multi-modal.md)教育交互（图文+语音同步反馈） | - 移动端弱网环境语音助手（AOQ 提供 3A 与抗丢包）<br>- 浏览器内嵌实时翻译/会议字幕（WebRTC 原生支持）<br>- 后端服务集成 ASR/TTS 流水线（WebSocket 快速对接）<br>- 多模态对话原型验证（WebSocket 低成本启动） |
|
||||
| **核心优势** | - 事件语义清晰（`input_audio_buffer.append` / `response.audio.delta`）<br>- 完整支持 Omni 专属能力（semantic VAD、工具调用、声音复刻、`idle_timeout_ms`）<br>- SDK 封装成熟（Python/JS/Java），开箱即用 | - **协议灵活性**：AOQ（移动端极致体验）、WebRTC（浏览器零依赖）、WebSocket（通用轻量）<br>- **模型泛化性**：一套框架接入全实时模型族<br>- **媒体栈可控性**：AOQ/WebRTC 支持自定义采集/渲染/编解码 |
|
||||
| **主要限制** | - 仅支持 WebSocket 协议，无 AOQ/WebRTC 能力<br>- 仅限 Omni 模型，无法接入 ASR/TTS 等专项模型<br>- `turbo` 模型参数不可调，灵活性受限 | - AOQ 不支持浏览器、不支持非 Omni 模型（如 Fun-ASR）<br>- WebRTC 在非浏览器环境需第三方库支持<br>- WebSocket 缺乏弱网优化与内置 3A，需自行实现 |
|
||||
|
||||
---
|
||||
|
||||
## 适用场景建议
|
||||
|
||||
### ✅ 选择 Realtime API 当：
|
||||
- **需覆盖多端生态**：同时支持 iOS/Android/HarmonyOS 原生 App（AOQ）、Web 浏览器（WebRTC）、后端服务（WebSocket）；
|
||||
- **弱网环境关键**：用户常处于移动网络波动、高丢包场景（如远程教育、户外巡检），需 QUIC 或 WebRTC 级别抗抖动能力；
|
||||
- **音视频双向实时性严苛**：如远程协作白板、AR 实时标注、多方会议语音增强，需端到端 <200ms 延迟；
|
||||
- **已有音视频技术栈**：团队熟悉 WebRTC 开发或已集成 AOQ SDK，希望复用现有采集/渲染/编解码逻辑；
|
||||
- **需混合模态能力**：既要语音对话，又要实时视频分析（如手势识别、表情反馈）。
|
||||
### 选择 Omni Realtime API 当：
|
||||
- ✅ 业务明确使用 `qwen-omni-*` 系列模型（如需语音+图像理解、文本+音频同步生成）；
|
||||
- ✅ 开发目标为 **服务端集成或 Web/桌面端应用**，且对弱网适应性要求不高；
|
||||
- ✅ 需要快速落地 **语义级语音活动检测（semantic_vad）、工具[函数调用](../concepts/function-calling.md)、声音复刻、静默主动引导** 等高级能力；
|
||||
- ✅ 团队熟悉 WebSocket 事件编程模型，倾向使用 DashScope 官方 Python/JS SDK 快速构建。
|
||||
|
||||
### ✅ 选择 Omni Realtime API 当：
|
||||
- **聚焦对话体验深度优化**：需精细控制 VAD 参数、动态启用联网搜索、灵活编排工具调用链路；
|
||||
- **快速验证与 MVP 开发**：Web 前端或 Python 服务端快速接入，无需协议适配、SDK 集成、[插件](../concepts/plugin.md)安装；
|
||||
- **纯语音+图文交互场景**：如智能客服机器人、语音助手、无障碍交互应用，无需视频流；
|
||||
- **需要结构化事件流**：偏好明确的 `session` / `input_buffer` / `conversation.item` 事件语义，便于状态机管理；
|
||||
- **预算敏感且模型能力匹配**：选用 `qwen-omni-turbo-realtime` 等低成本模型，牺牲参数自由度换取性价比。
|
||||
### 选择 Realtime API（广义）当：
|
||||
- ✅ 需要 **跨平台深度适配**：iOS/Android/HarmonyOS 原生 App → 选 **AOQ**；浏览器 Web 应用 → 选 **WebRTC**；后端微服务 → 选 **WebSocket**；
|
||||
- ✅ 业务涉及 **多种实时模型组合**：例如前端用 Omni 对话 + 后端调用 Fun-ASR 做离线转写 → 必须通过 Realtime API 的协议分发能力协调；
|
||||
- ✅ 对 **弱网稳定性、回声消除、自动增益、低延迟抖动控制** 有硬性要求 → **AOQ 是唯一选择**；
|
||||
- ✅ 需要 **完全掌控音视频链路**：如接入自研麦克风硬件、定制视频美颜滤镜、对接专业播放器 → AOQ/WebRTC 提供 `ExternalStream` 接口。
|
||||
|
||||
> ⚠️ 注意：若业务需同时使用 `Fun-ASR`（独立语音识别）和 `qwen3.5-omni-realtime`（全模态对话），**必须选用 Realtime API 的 WebSocket 协议**——Omni Realtime API 不提供单模态模型入口。
|
||||
> ⚠️ 注意：若仅使用 Omni 模型且运行在浏览器或服务端，**Omni Realtime API 与 Realtime API 的 WebSocket 路径功能高度重叠**，此时优先选用 Omni Realtime API（语义更精准、文档更聚焦、SDK 更专用）；若需 AOQ 或 WebRTC 能力，则必须走 Realtime API 框架。
|
||||
|
||||
---
|
||||
|
||||
## 技术选型参考（面向开发者）
|
||||
## 技术选型决策树（面向开发者）
|
||||
|
||||
| 你的需求 | 推荐方案 | 关键理由 |
|
||||
|----------|-----------|-----------|
|
||||
| “我要在安卓 App 里嵌入低延迟语音客服，用户常在地铁里使用” | **Realtime API + AOQ** | AOQ 的 QUIC 传输在弱网下建连更快、丢包恢复更强，Opus [插件](../concepts/plugin.md)保障音频质量 |
|
||||
| “我正在做 Web 端在线陪练应用，需实时语音+文字+简单图像理解” | **Omni Realtime API** | WebSocket 接入快，`input_image_buffer.append` + `semantic_vad` + `tools` 可一站式满足需求，无需处理 WebRTC 兼容性 |
|
||||
| “我们已有 WebRTC 视频会议系统，想叠加 AI 实时字幕+翻译” | **Realtime API + WebRTC** | 复用现有 WebRTC 媒体轨道，直接注入音频流；`qwen3.5-livetranslate-flash-realtime` 专为实时翻译优化 |
|
||||
| “后端服务需批量发起语音合成任务，不涉及实时交互” | **Realtime API + WebSocket**（或考虑非实时 TTS API） | WebSocket 成本低、易运维；但注意：若只需合成，非实时 `qwen-audio-3.0` 更经济 |
|
||||
| “需要模型自主调用天气 API 并返回口语化结果，且支持用户打断重说” | **Omni Realtime API + `qwen3.5-omni-realtime`** | 唯一支持 `tools` + `enable_search` + `smooth_output` + `semantic_vad` 组合的接口 |
|
||||
| “团队无音视频开发经验，只想用几行代码跑通语音对话 demo” | **Omni Realtime API** | Python SDK 3 行代码即可连接、发送音频、接收文本+音频，文档示例完备 |
|
||||
```mermaid
|
||||
graph TD
|
||||
A[需求起点] --> B{是否必须使用 qwen-omni-* 模型？}
|
||||
B -->|否| C[→ Realtime API：选择 AOQ/WebRTC/WS 适配对应模型]
|
||||
B -->|是| D{部署环境与协议要求？}
|
||||
D -->|iOS/Android/HarmonyOS 原生 App<br>且弱网场景关键| E[→ Realtime API + AOQ]
|
||||
D -->|浏览器 Web 应用<br>需零插件部署| F[→ Realtime API + WebRTC]
|
||||
D -->|服务端/桌面端/快速验证<br>无需弱网优化| G[→ Omni Realtime API<br>（推荐）或 Realtime API + WebSocket]
|
||||
G --> H{是否需要 semantic_vad/工具调用/声音复刻？}
|
||||
H -->|是| I[→ Omni Realtime API<br>（功能最全）]
|
||||
H -->|否| J[→ Realtime API + WebSocket<br>（更通用，但 Omni 专属能力需确认支持）]
|
||||
```
|
||||
|
||||
> 💡 **终极建议**：
|
||||
> - **先跑通 Omni Realtime API**：用其快速验证模型效果、对话逻辑与业务流程；
|
||||
> - **再评估是否需协议升级**：若遇到弱网卡顿、端侧兼容问题、或需视频能力，则切换至 Realtime API 并按端选协议；
|
||||
> - **始终遵循最小权限原则**：API Key 不出现于前端代码，AOQ [Token](../concepts/token.md) 必须服务端签发，WebSocket 连接建议经反向代理鉴权。
|
||||
|
||||
---
|
||||
*最后更新：2024年10月*
|
||||
**最后建议**：
|
||||
- 新项目优先评估 **Omni Realtime API** —— 它是 Omni 模型能力的“黄金标准”实现，文档完备、SDK 稳健、事件语义直观；
|
||||
- 若项目已存在 AOQ/WebRTC 基础设施，或需混合接入 ASR/TTS 等模型，请直接采用 **Realtime API 框架**，并依据终端类型选择协议；
|
||||
- 永远避免将 API Key 硬编码于客户端；AOQ 必须经服务端签发临时 [Token](../concepts/token.md)，WebSocket/WebRTC 建议同样通过后端代理鉴权。
|
||||
|
||||
## 被对比主题页
|
||||
|
||||
- [realtime api user guide](../api/realtime-api-user-guide.md)
|
||||
- [omni realtime api](../api/omni-realtime-api.md)
|
||||
- [realtime api user guide](../api/realtime-api-user-guide.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
# 异步任务
|
||||
|
||||
异步任务是百炼平台为处理长耗时模型推理（如文生图、文生视频、3D生成、语音识别等）而设计的核心执行机制：调用方发起请求后立即获得唯一 `task_id`，无需阻塞等待结果，后续通过轮询或事件通知方式获取最终输出。
|
||||
|
||||
## 在百炼平台的不同场景中，这个概念如何使用
|
||||
|
||||
- **图像生成**：`wanx-v1`、`wanx-sketch-to-image-lite`、`shoemodel-v1` 等模型**必须**使用异步模式；即使支持同步的模型（如 `wan2.6-t2i`），在高分辨率或多图批量生成时也建议切至异步以提升稳定性。
|
||||
- **视频生成**：所有 Video Generation API（包括万相2.7、Kling、PixVerse、Vidu、数字人等）**强制异步**，请求头必须携带 `X-DashScope-Async: enable`，否则返回明确错误。
|
||||
- **3D生成**：Tripo 模型（`Tripo/Tripo-H3.1`、`Tripo/Tripo-P1.0`）**仅支持异步**，不提供同步接口，且地域强约束于华北2（北京）。
|
||||
- **多模态大模型推理**：当调用 `qwen-vl-plus`、`qwen-audio-plus` 等支持文件输入的模型，且输入含大尺寸图像/音频/视频时，平台自动降级为异步任务（即使请求未显式声明），避免超时失败。
|
||||
- **文件解析与知识库构建**：虽非模型推理本身，但大文件（如百页PDF）的文本结构化解析过程也以异步任务形式执行，可通过 `task_id` 查询解析进度与结果。
|
||||
|
||||
> ✅ **统一行为**：所有异步任务均遵循「创建 → 查询/监听 → 获取结果」三步流程，`task_id` 是贯穿全生命周期的唯一凭证。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
| 参数/配置 | 说明 | 注意事项 |
|
||||
|-----------|------|----------|
|
||||
| `task_id` | 异步任务全局唯一标识符（UUID格式），由创建接口返回 | 必须妥善保存；用于轮询、取消、下载结果；有效期通常为 24 小时（3D/视频任务）或 48 小时（部分图像任务） |
|
||||
| `X-DashScope-Async: enable` | **必需请求头**，显式声明启用异步模式 | 缺失将导致 `400 Bad Request` 或 `synchronous calls not supported` 错误；不可与同步端点混用 |
|
||||
| 轮询间隔 | 建议 ≥15 秒（3D）、≥30 秒（视频）、≥5 秒（图像） | 频繁轮询易触发限流；生产环境应结合指数退避策略 |
|
||||
| 事件通知（推荐） | 配置 HTTP 回调 URL 或 RocketMQ 主题接收 `dashscope:System:AsyncTaskFinish` 事件 | 替代轮询，降低延迟与请求压力；需自行实现幂等处理（同一 `task_id` 可能重复推送） |
|
||||
| 结果有效期 | 图像 URL 通常 24 小时，3D/视频资源 URL 通常 2 小时 | 务必在有效期内完成下载或持久化；过期后需重新查询任务获取新链接 |
|
||||
|
||||
## 面向开发者，简洁实用
|
||||
|
||||
- **不要轮询，优先用事件**：在服务端部署 HTTP 回调或 RocketMQ 消费者，监听 `AsyncTaskFinish` 事件，这是最高效、最可靠的方式。
|
||||
- **`task_id` 是你的主键**：所有异步操作（查询、取消、结果下载）都依赖它——请记录到数据库或日志，并设置 TTL 清理策略。
|
||||
- **检查请求头**：务必确认 `X-DashScope-Async: enable` 已设置，且 `Content-Type: application/json` 正确；漏掉任一都会失败。
|
||||
- **地域与模型严格匹配**：异步任务的 `task_id` 只能在创建时使用的地域（如 `cn-beijing`）和 Workspace ID 下查询；跨地域调用 `GET /api/v1/tasks/{task_id}` 返回 `UNKNOWN`。
|
||||
- **错误处理要覆盖三种状态**：
|
||||
- `status: "QUEUED"` / `"RUNNING"` → 继续等待；
|
||||
- `status: "SUCCEEDED"` → 解析 `output` 字段（含图片/视频/GLB URL、预览图、元数据）；
|
||||
- `status: "FAILED"` → 查看 `error.code` 和 `error.message`（如 `InvalidParameter`, `ResourceNotReady`, `QuotaExceeded`）。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [more about models](../api/more-about-models.md)
|
||||
- [image generation](../api/image-generation.md)
|
||||
- [3d generation](../api/3d-generation.md)
|
||||
- [video generation api](../api/video-generation-api.md)
|
||||
- [file management api](../api/file-management-api.md)
|
||||
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# 文件处理
|
||||
|
||||
文件处理是百炼平台中对非结构化与半结构化数据（如 PDF、Word、Excel、CSV、JPG、PNG 等）进行上传、解析、引用、转换与输出的核心能力集合，贯穿模型调用、智能体执行、知识库构建与数据连接等关键链路。它不直接参与模型推理，而是为大模型和业务逻辑提供安全、标准化的文件输入通道与结果交付载体。
|
||||
|
||||
## 在百炼平台的不同场景中，这个概念如何使用
|
||||
|
||||
- **模型调用场景**：通过 `file management API` 上传文件获取 `file_id`，在 `chat/completions` 或[多模态](multi-modal.md)请求（如 `qwen-vl-plus`）中以 `file_id` 或 `oss://` URL 引用；需注意 `purpose` 参数（`assistants` / `vision`）决定文件是否可用于文本理解或视觉模型。
|
||||
- **智能体（Agent）场景**：用户上传附件后，系统自动识别 MIME 类型与内容特征，结合 Skill 的 `description` 语义匹配，触发 `pdf`、`xlsx` 等官方 Skill 执行解析、格式转换或表格生成，并以新文件形式返回结果。
|
||||
- **RAG 与知识库场景**：通过应用支持模块上传 `.pdf`/`.docx` 等文档，平台调用文档理解能力完成切片、向量化与索引构建；文件作为知识源参与检索增强，不直接参与对话流但影响生成质量。
|
||||
- **数据连接场景**：文件连接器（File Connector）将本地或 OSS 中的静态文档批量导入平台，经统一解析后形成可检索的知识集；表格连接器则处理 Excel/CSV，支持 `image_url` 字段用于[多模态](multi-modal.md)向量构建。
|
||||
- **异步任务与临时资源场景**：调用图像/视频生成等异步模型时，需先通过 `getPolicy` 接口获取临时 OSS 上传策略，生成 `oss://` URL 并在请求头中显式启用 `X-DashScope-OssResourceResolve: enable`，该 URL 48 小时后自动失效。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
| 参数 | 所属模块 | 说明 | 注意事项 |
|
||||
|------|----------|------|----------|
|
||||
| `file_id` | File Management API | 文件唯一标识符，上传成功后返回，全局唯一且不可复用 | 删除后所有关联调用立即失效；不可修改 purpose |
|
||||
| `purpose` | File Management API | 取值 `assistants`（默认，适用于文本类模型）或 `vision`（仅限[多模态](multi-modal.md)模型如 `qwen-vl`） | 同一文件若需双用途，必须分别上传两次并指定不同 purpose |
|
||||
| `expire_in_seconds` | More about Models | 临时 API Key 有效期（1–1800 秒） | 用于前端直传等不可信环境，到期自动作废 |
|
||||
| `X-DashScope-OssResourceResolve: enable` | Model Calling (Multi-modal) | 使用 `oss://` URL 时必需的请求头 | 缺失将导致模型拒绝访问文件资源 |
|
||||
| `MD5` | Application Support | 文件上传完整性校验字段 | 必填，用于服务端比对防止传输损坏 |
|
||||
| `bailian-connector-access` / `bailian-datahub-access` | Data Connection | OSS Bucket 标签，区分连接器类型权限 | 前者用于文件/表格连接器（值 `ReadAndWrite`），后者用于数据枢纽型 OSS 连接（值 `read`），不可混用 |
|
||||
|
||||
> ⚠️ 共同限制：单文件 ≤ 512 MB；禁止 `.exe`、`.zip`、`.jar` 等可执行/压缩格式；PDF 后缀必须为小写 `pdf`；文件默认永久保留，需显式 DELETE 清理。
|
||||
|
||||
## 面向开发者，简洁实用
|
||||
|
||||
- ✅ **首选路径**：生产环境优先使用 `file management API` 上传 + `file_id` 引用，避免临时 URL 的 48 小时生命周期约束；
|
||||
- ✅ **多模态必做**：调用 `qwen-vl-*` 模型前，务必确认 `purpose=vision`，否则图像无法被识别；
|
||||
- ✅ **Skill 开发提示**：自定义 Skill ZIP 包 ≤ 10 MB，运行于沙箱，禁止外网访问；输出文件需通过标准返回协议（如 `{"file": "result.xlsx"}`）交付；
|
||||
- ✅ **调试建议**：文件未生效？检查 `file_id` 是否有效、`purpose` 是否匹配模型、请求头是否缺失 `X-DashScope-OssResourceResolve`、OSS Bucket 标签是否正确；
|
||||
- ❌ **禁止行为**：不要重复上传同名文件期望复用 `file_id`（每次生成新 ID）；不要在 Skill 中尝试写数据库或调用外部 API（沙箱限制）；不要将临时 `oss://` URL 用于长期存储或压测（QPS 限 100，且非生产级设计）。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [file management api](../api/file-management-api.md)
|
||||
- [data connection overview](../guides/data-connection-overview.md)
|
||||
- [skill](../guides/skill.md)
|
||||
- [more about models](../api/more-about-models.md)
|
||||
- [application support](../guides/application-support.md)
|
||||
|
||||
|
||||
@@ -1,50 +1,48 @@
|
||||
# 函数调用
|
||||
|
||||
函数调用（Function Calling）是百炼平台支持的一种结构化模型交互能力，允许开发者在请求中声明可被模型识别并调用的工具函数（如搜索、计算、数据库查询等），由模型自主决定是否调用、调用哪个函数及传入何种参数，最终返回标准 JSON 格式的函数调用请求（而非自由文本）。该机制是构建可靠 AI Agent 的核心基础设施。
|
||||
函数调用（Function Calling）是百炼平台支持的一种结构化工具协同能力，指大语言模型在生成响应过程中，主动识别用户意图并按预定义 Schema 生成结构化工具调用请求（而非自由文本），交由外部系统执行后，再将结果注入后续推理。该机制实现了“思考→规划→执行→整合”的闭环，是构建可靠智能体（Agent）的核心基础设施。
|
||||
|
||||
## 在百炼平台的不同场景中，这个概念如何使用
|
||||
|
||||
函数调用能力已在多个模型和业务场景中深度集成，使用方式因模型类型与接口协议略有差异，但逻辑一致：
|
||||
函数调用能力在百炼平台中并非全局统一启用，其支持范围、行为细节和配置方式因接入协议与模型而异：
|
||||
|
||||
- **通用大模型（如 `qwen3.7-plus`、`qwen3.5-omni-plus`）**：原生支持 OpenAI 兼容的 `functions` / `tools` 参数。开发者通过 `tools` 字段传入函数定义（含 `name`、`description`、`parameters`），模型在响应中返回 `tool_calls` 数组；平台自动解析并返回结构化结果，无需额外后处理。
|
||||
|
||||
- **意图理解专用模型（`tongyi-intent-detect-v3`）**：专为函数调用优化，毫秒级响应，支持高并发意图识别与函数名/参数生成。需在 `system` 消息中明确声明 `Response in INTENT_MODE.`，并可选提供预定义意图字典（即函数列表），模型将严格按字典输出标准化意图标识与参数。
|
||||
- **DashScope 原生接口**：完全支持自定义函数调用。开发者通过 `tools` 参数传入 OpenAI 风格的工具定义（含 `name`、`description`、`parameters` JSON Schema），模型返回 `output.choices[0].message.tool_calls` 数组，包含 `function.name` 和 `function.arguments` 字符串（需 `json.loads` 解析）。支持多工具并行调用、嵌套调用及调用后自动追加执行结果继续推理（需设置 `enable_tool_choice: "auto"` 或指定 `tool_choice`）。
|
||||
|
||||
- **全模态与实时语音模型（如 `qwen-audio-3.0-realtime-plus`、`qwen3.5-omni-plus-realtime`）**：在流式语音对话中支持低延迟函数调用触发，适用于智能助手、语音控制等场景。需启用 `enable_function_calling=true`（部分模型为默认开启），函数调用事件将作为独立消息帧（`tool_call` 类型）实时推送。
|
||||
- **Anthropic 兼容 Messages 接口**：支持 `tool_use` 块输出，使用 Anthropic 原生 `tools` 定义语法（`input_schema` 替代 `parameters`），响应中以 `content` 数组中的 `tool_use` 类型块返回调用请求。注意：`system` 提示词长度受限于 4096 token，可能影响复杂工具描述的完整性。
|
||||
|
||||
- **不支持函数调用的模型**：如 `qwen-long`、`qwen3-rerank`、`text-embedding-v4` 等向量/重排序/超长文本模型，明确不支持该能力，请求中若携带 `tools` 将被忽略或报错。
|
||||
- **OpenAI 兼容 Chat Completions 接口**：**不支持流式工具调用响应解析**——虽然请求可携带 `tools`，但流式响应（`stream: true`）的 `delta.tool_calls` 可能缺失参数或顺序错乱；建议在非流式模式下使用，并严格校验 `finish_reason == "tool_calls"` 后再解析 `message.tool_calls`。
|
||||
|
||||
> ✅ 提示：函数调用是**模型能力属性**，非接口层功能。即使使用 OpenAI 兼容路径（`/v1/chat/completions`），也必须选用明确标注支持 Function Calling 的模型（见 [model experience](guides/model-experience.md) 中各模型的能力矩阵），否则 `tools` 字段无效。
|
||||
- **OpenAI 兼容-Responses 模式**：仅支持平台预置的三类内置工具（联网搜索、代码解释器、网页内容提取），**不可自定义 `tools`**。调用逻辑由平台自动触发与编排，开发者只需在 `messages` 中提供自然语言请求，无需声明工具定义。
|
||||
|
||||
> ⚠️ 注意：`qwen3.7-max` 等强推理模型默认禁用结构化输出（含函数调用），如需启用，请优先选用 `qwen3.7-plus` 或 `qwen3.7-flash`；同时，联网搜索与函数调用互斥，二者不可同时开启。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
| 参数 | 说明 | 示例/要求 | 注意事项 |
|
||||
|------|------|-----------|----------|
|
||||
| `tools` | 必选（启用函数调用时）。数组，每个元素为一个工具定义对象，含 `type="function"`、`function.name`、`function.description`、`function.parameters`（JSON Schema） | `[{ "type": "function", "function": { "name": "search_web", "description": "Search the web for up-to-date information", "parameters": { "type": "object", "properties": { "query": { "type": "string" } } } } }]` | `parameters` 必须为合法 JSON Schema，不支持 `anyOf`/`oneOf`；建议字段数 ≤ 8，避免模型解析失败 |
|
||||
| `tool_choice` | 可选。控制模型调用行为：`"auto"`（默认，由模型决定）、`"none"`（禁用）、`{"type": "function", "function": {"name": "xxx"}}`（强制指定） | `"auto"` 或 `{ "type": "function", "function": { "name": "get_weather" } }` | 强制指定时，若模型无法生成有效参数，可能返回空 `arguments` 或报错 |
|
||||
| `response_format: { "type": "json_object" }` | 推荐搭配使用。确保模型以 JSON 格式输出（包括 `tool_calls` 字段），提升解析稳定性 | `{ "type": "json_object" }` | 部分模型（如 `qwen3.7-flash`）对 JSON 输出支持更鲁棒，推荐优先选用 |
|
||||
| `enable_function_calling`（部分模型） | 部分实时/语音模型需显式启用（如 `qwen-audio-3.0-realtime-plus`） | `true` | 查阅对应模型文档确认是否需要此参数 |
|
||||
| 参数 | 所属接口 | 说明 | 示例值 |
|
||||
|------|----------|------|--------|
|
||||
| `tools` | DashScope、Anthropic 兼容 | 工具定义列表，格式为 OpenAI 或 Anthropic 规范 | `[{"type": "function", "function": {"name": "get_weather", "description": "...", "parameters": {...}}}]` |
|
||||
| `tool_choice` | DashScope | 控制模型是否调用工具及调用策略 | `"auto"`（默认）、`"none"`、`{"type": "function", "function": {"name": "get_weather"}}` |
|
||||
| `enable_tool_choice` | DashScope（旧版别名） | 同 `tool_choice`，已逐步被后者替代 | `"auto"` |
|
||||
| `response_format` | DashScope | 强制结构化输出格式，与函数调用协同使用 | `{"type": "json_object"}`（需配合 `tools` 使用） |
|
||||
| `enable_search` | DashScope | 启用内置联网搜索（与自定义 `tools` 互斥） | `true` |
|
||||
| `tools`（OpenAI 兼容） | [OpenAI 兼容接口](openai-compatible-interface.md) | 仅用于非流式请求；流式响应中 `delta.tool_calls` 不可靠 | 同上 |
|
||||
|
||||
- **SDK 使用要点**：
|
||||
- Python SDK：`dashscope.Generation.call(..., tools=..., tool_choice=...)`
|
||||
- Java SDK：`GenerationParam.builder().tools(...).toolChoice(...).build()`
|
||||
- WebSocket 流式调用：函数调用事件以独立 `tool_call` 消息类型推送，需监听 `event == "tool_call"` 并解析 `content` 字段
|
||||
|
||||
- **安全与调试**：
|
||||
- 函数名与参数应使用小写字母+下划线命名（如 `get_user_profile`），避免特殊字符；
|
||||
- 生产环境建议对 `tool_calls` 响应做白名单校验（验证 `name` 是否在预设函数集中）；
|
||||
- 若模型返回无效 JSON 或空 `arguments`，可添加 `system` 消息强化指令，例如：`"Always output valid JSON for tool calls. Never omit required parameters."`
|
||||
- **认证与路由**：所有函数调用均需标准鉴权（`Authorization: Bearer <API_KEY>`），且必须使用对应协议的 Endpoint（如 DashScope 原生接口使用 `/api/v1/services/aigc/text-generation/generation`）。
|
||||
- **输入构造**：工具调用依赖 `messages` 中清晰的用户指令（如“查上海今天天气”），模型据此生成符合 `tools` Schema 的调用请求；避免在 `system` 提示中重复定义工具，应集中于 `tools` 参数。
|
||||
- **错误处理**：若 `arguments` 解析失败（JSON 格式错误）、工具执行超时或返回异常，需由业务层捕获并构造 error message 追加至 `messages` 后重试。
|
||||
|
||||
## 面向开发者，简洁实用
|
||||
|
||||
- ✅ **快速起步**：选 `qwen3.7-plus` 或 `tongyi-intent-detect-v3` → 构造 `tools` 数组 → 发起请求 → 解析 `response.choices[0].message.tool_calls`。
|
||||
- ⚠️ **避坑提示**：不要在不支持的模型（如 `qwen-long`）上尝试函数调用；子空间调用需确保该空间已授权所用模型；[异步任务](asynchronous-task.md)（如视频生成）不支持函数调用，仅同步/流式接口可用。
|
||||
- 🚀 **进阶建议**：结合 `response_format: json_object` + `temperature=0` 提升结构化输出稳定性；对高敏感函数（如支付、删除），务必在服务端二次校验参数合法性与用户权限。
|
||||
- ✅ **推荐路径**：生产环境首选 **DashScope 原生接口** + `qwen3.7-plus`，它提供最完整的工具定义、调用控制与错误反馈能力。
|
||||
- ✅ **快速验证**：开发调试阶段可用 **OpenAI 兼容-Responses** 模式，零配置体验内置工具链（搜索/代码执行），但无法扩展自定义能力。
|
||||
- ❌ **规避陷阱**：勿在 [OpenAI 兼容接口](openai-compatible-interface.md)中依赖流式 `tool_calls`；勿在 `qwen3.7-max` 上启用 `tools`；勿同时设置 `enable_search: true` 和自定义 `tools`。
|
||||
- 🛠️ **调试技巧**：开启 `stream: false` + `debug: true`（DashScope）可获取完整推理 trace，观察模型何时、为何选择调用某工具；使用 `seed` 固定随机性便于复现问题。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [qwen api reference](../api/qwen-api-reference.md)
|
||||
- [more about models](../api/more-about-models.md)
|
||||
- [model experience](../guides/model-experience.md)
|
||||
- [more models](../api/more-models.md)
|
||||
- [toolkits and frameworks](../api/toolkits-and-frameworks.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,42 +1,68 @@
|
||||
# 长期记忆
|
||||
|
||||
长期记忆是百炼平台提供的结构化用户状态持久化能力，用于突破大模型上下文窗口限制，实现跨会话、跨轮次的用户偏好、关键事件与结构化属性的自动提取、存储与语义召回。它由平台统一托管的记忆专用模型驱动，无需开发者自行训练或部署 Embedding 模型。
|
||||
长期记忆是百炼平台提供的结构化、持久化用户信息管理能力，用于突破大模型单次会话的上下文限制，实现跨对话、跨会话的用户偏好、待办事项、关键事件等信息的自动提取、语义存储与智能召回。它不是简单的文本缓存，而是基于专用抽取模型与语义向量引擎构建的可检索、可联动、可编程的记忆基础设施。
|
||||
|
||||
## 在百炼平台的不同场景中如何使用
|
||||
## 在百炼平台的不同场景中，这个概念如何使用
|
||||
|
||||
- **智能体（Agent）持续性增强**：通过 `AddMemory` 自动从对话中提炼关键信息（如“每天9点提醒我喝水”），再在后续交互中用 `SearchMemory` 语义检索召回，使 Agent 具备上下文延续能力；OpenClaw [插件](plugin.md)支持 `autoCapture`（对话结束自动写入）和 `autoRecall`（对话开始前自动注入），实现零代码集成。
|
||||
- **用户画像构建**：配合 `ProfileSchema` 系统，定义结构化字段（如 `age`, `occupation`, `diet_preference`），在 `AddMemory` 中指定 `profile_schema` 参数，即可从自然对话中自动抽取并聚合为标准化用户画像，再通过 `GetUserProfile` 获取快照。
|
||||
- **RAG 增强补充**：作为 RAG 的补充层，长期记忆聚焦于**用户个体状态**（而非通用知识库），适用于个性化推荐、习惯追踪、服务历史回溯等场景；可与知识库检索并行调用，共同注入 LLM 提示词。
|
||||
- **应用级状态管理**：替代自建数据库存储轻量级用户状态（如设置项、偏好标签、任务进度），通过标准 CRUD 接口（`ListMemory`/`DeleteMemory`/`UpdateMemory`）实现生命周期控制，降低运维复杂度。
|
||||
- **智能体（Agent）应用**：作为核心上下文增强组件，长期记忆使 Agent 能“记住”用户历史指令（如“我过敏花生”）、习惯（如“默认用简体中文回复”）或承诺事项（如“下周三提醒我续保”），在后续交互中通过 `SearchMemory` 自动注入提示词，显著提升个性化与连贯性。注意：当前 LLM 应用层仅原生支持短期记忆（0–30 轮），长期记忆需显式调用 API 或通过 OpenClaw 插件启用 `autoRecall`。
|
||||
|
||||
- **用户画像构建**：通过指定 `profile_schema_id`，长期记忆可将非结构化对话（如“我今年35岁，在杭州做设计师”）自动映射为结构化字段（`age: 35`, `city: "杭州"`, `occupation: "设计师"`），支持多轮渐进填充，并与 `GetUserProfile` 联动输出完整画像。
|
||||
|
||||
- **记忆库（Memory Library）统一管理**：所有记忆片段均归属至逻辑隔离的记忆库（`memory_library_id`），支持多应用共享（按 `user_id` 隔离）、规则驱动（`project_id` 指定抽取/过期策略）和元数据分类（`meta_data` 自定义标签），是构建企业级用户认知中枢的基础单元。
|
||||
|
||||
- **插件化集成（OpenClaw）**：无需编码即可启用全自动捕获（`autoCapture`）与召回（`autoRecall`），插件在对话收尾时自动调用 `AddMemory` 和 `SearchMemory`，开发者只需配置规则与 Schema。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 推荐值 |
|
||||
|--------|------|------|------|--------|
|
||||
| `user_id` | string | 是 | 用户唯一标识，64 字符内；所有接口必须传入，用于严格隔离用户数据空间 | `"usr_abc123"` |
|
||||
| `memory_library_id` | string | 否 | 目标记忆库 ID（32 字符）；不传则使用账号默认库（控制台可创建多个库） | 控制台「记忆库列表」获取 |
|
||||
| `messages` / `custom_content` | array / string | 互斥必填（仅 `AddMemory`） | `messages`: 最多 50 条 role/content 对话；`custom_content`: ≤512 字符纯文本（绕过自动提取） | 优先用 `messages` 实现语义理解 |
|
||||
| `profile_schema` | string | 否（仅需画像时） | 用户画像模板 ID；需先调用 `CreateProfileSchema` 创建，否则忽略抽取逻辑 | 控制台「画像模板」页获取 |
|
||||
| `top_k` | integer | 否（`SearchMemory`） | 召回最大条数，默认 10；范围 1–100 | 3–10（平衡精度与性能） |
|
||||
| `min_score` | double | 否（`SearchMemory`） | 相似度阈值，默认 0.3；范围 [0,1]，低于此值结果被过滤 | 0.5–0.7（高精度场景建议 ≥0.6） |
|
||||
| `enable_rerank` | boolean | 否（`SearchMemory`） | 是否启用重排序（提升相关性），默认 `false` | `true`（对召回质量敏感时启用） |
|
||||
| `user_id` | string | 是 | 用户唯一标识（≤64 字符），所有操作以此隔离数据空间 | 业务系统用户 ID（如 `uid_12345`） |
|
||||
| `messages` / `custom_content` | array / string | 互斥必填 | `messages`: 对话历史（最多 50 条）；`custom_content`: 直接文本（≤512 字符） | 优先用 `messages` 让模型自动理解上下文 |
|
||||
| `memory_library_id` | string | 否 | 显式指定记忆库 ID（≤32 字符）；不填则使用默认库 | 控制台创建后复制 ID，多租户场景建议显式指定 |
|
||||
| `profile_schema_id` | string | 否 | 关联用户画像 Schema ID，触发结构化抽取 | 需先调用 `CreateProfileSchema` 创建 |
|
||||
| `top_k`（SearchMemory） | integer | 否 | 检索返回条数（1–100） | 3–10（平衡精度与 token 开销） |
|
||||
| `min_score`（SearchMemory） | double | 否 | 相似度阈值 [0.0, 1.0] | 0.5–0.7（避免噪声或漏召） |
|
||||
| `enable_rerank` / `enable_judge` / `enable_rewrite`（SearchMemory） | boolean | 否 | 高级搜索开关，需显式启用 | `enable_rerank=True` 提升排序质量；`enable_judge=True` 过滤无关项 |
|
||||
|
||||
> ⚠️ 注意：
|
||||
> - 所有记忆**默认永不过期**，无自动失效机制；业务需通过 `DeleteMemory` 或按规则主动清理。
|
||||
> - `UpdateMemory` 仅支持增量更新 `meta_data`（合并新键值对），且需直接调用 REST API（Python SDK 当前未封装）。
|
||||
> - `project_id`（记忆规则 ID）可选，用于绑定定制化提取/过滤策略；未指定则使用记忆库默认规则。
|
||||
> ⚠️ 注意事项：
|
||||
> - `project_id`（记忆片段规则 ID）非必需：未传时系统自动选用默认规则；规则中设置的“过期时间”仅影响新写入记忆的调度策略，**底层存储无自动物理删除机制**，业务侧需自行清理。
|
||||
> - 所有接口限流为阿里云账号级别：`AddMemory` ≤120 QPM，`SearchMemory` ≤300 QPM，总量 ≤3000 QPM。
|
||||
> - `custom_content` 和单条 `messages.content` 均严格限制 ≤512 字符，超长内容将被截断，建议预处理摘要。
|
||||
|
||||
## 开发者提示
|
||||
## 面向开发者，简洁实用
|
||||
|
||||
- **认证方式**：所有请求 Header 必须携带 `Authorization: Bearer $DASHSCOPE_API_KEY`（API Key 从[控制台](https://help.aliyun.com/zh/model-studio/get-api-key)获取）。
|
||||
- **SDK 推荐**：安装 `agentscope-runtime>=1.1.5`，直接调用 `AddMemory`、`SearchMemory`、`ListMemory`、`DeleteMemory` 四个封装工具；`UpdateMemory` 需手动发起 PATCH 请求。
|
||||
- **限流控制**：账号级总 QPM ≤3000；其中 `AddMemory` ≤120 QPM，`SearchMemory` ≤300 QPM —— 生产环境请做好降级与重试。
|
||||
- **调试建议**：控制台「记忆检索」页支持实时测试查询、开启改写/重排序/意图判别，验证效果后再上线。
|
||||
- **快速起步**：
|
||||
```python
|
||||
# 安装最新 SDK
|
||||
pip install agentscope-runtime>=1.1.5
|
||||
|
||||
# 添加记忆（自动抽取）
|
||||
from agentscope.tools import AddMemory
|
||||
await AddMemory().arun(user_id="u123", messages=[{"role":"user","content":"帮我订明天下午3点的会议室"}])
|
||||
|
||||
# 检索记忆（带语义重写+重排）
|
||||
from agentscope.tools import SearchMemory
|
||||
result = await SearchMemory().arun(
|
||||
user_id="u123",
|
||||
messages=[{"role":"user","content":"我最近有什么会议安排？"}],
|
||||
top_k=5,
|
||||
min_score=0.6,
|
||||
enable_rewrite=True,
|
||||
enable_rerank=True
|
||||
)
|
||||
```
|
||||
|
||||
- **生产建议**：
|
||||
- 写入前对 `messages` 做轻量清洗（移除系统提示、冗余确认语句），提升抽取准确率；
|
||||
- 检索时优先用 `messages`（含角色上下文）而非裸 `query`，语义更鲁棒；
|
||||
- 敏感信息（如身份证号）勿直接写入，应脱敏或走加密存储通道；
|
||||
- 定期调用 `ListMemory` + `DeleteMemory` 清理过期/无效记忆，避免噪声累积。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [long term memory new](../api/long-term-memory-new.md)
|
||||
- [memory library overview](../guides/memory-library-overview.md)
|
||||
- [application support](../guides/application-support.md)
|
||||
- [application component api reference](../api/application-component-api-reference.md)
|
||||
- [llm application](../guides/llm-application.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,39 +1,58 @@
|
||||
# 模型上下文协议
|
||||
|
||||
模型上下文协议（Model Context Protocol, MCP）是阿里云百炼平台提供的标准化工具调用协议，用于在大模型应用（如智能体、工作流）与外部服务之间建立安全、可发现、可扩展的双向通信通道。它基于开源 MCP 标准实现，统一抽象工具接入方式，使大模型能自动理解、发现并结构化调用各类服务（如地图、天气、[长期记忆](long-term-memory.md)等），无需为每个工具单独编写适配逻辑。
|
||||
模型上下文协议（Model Context Protocol，简称 MCP）是阿里云百炼平台提供的标准化、安全、可扩展的工具接入协议，用于在大语言模型与外部能力（如地图、搜索、数据库、图像生成等）之间建立统一通信通道。它基于开源 MCP 规范（[modelcontextprotocol.io](https://modelcontextprotocol.io/)）实现，并深度集成百炼平台的智能体运行时、工作流引擎与云服务基础设施，使开发者无需重复开发适配层即可复用和编排各类工具能力。
|
||||
|
||||
## 在百炼平台的不同场景中如何使用
|
||||
|
||||
- **智能体应用（Agent 2.0）**：MCP 作为“可规划工具”深度集成。大模型根据对话上下文自主判断是否调用、调用哪个工具（如 `maps_weather`）、传入哪些参数，全程自动完成工具发现、参数生成与结果解析。单个智能体最多配置 5 个 MCP 服务，支持动态决策与思考链可视化。
|
||||
MCP 是百炼平台统一的工具抽象层，已全面替代旧版“插件”机制（见 `llm application` 文档说明），所有外部能力均通过 MCP 协议接入。具体使用方式依应用类型而异：
|
||||
|
||||
- **工作流应用**：需显式添加 **MCP 节点**，手动选择目标工具（如仅启用 `maps_route`），输入参数必须由上游节点（如大模型节点）以 JSON Schema 兼容格式输出。适用于需要确定性编排、多步骤协同或结果后处理的场景。
|
||||
- **智能体应用（Agent）**：
|
||||
模型根据用户自然语言意图自主决策是否调用 MCP 工具、选择哪个工具、传入哪些参数，并支持多轮动态调用（如先搜索→再解析→最后绘图）。最多可同时启用 5 个 MCP 服务。配置路径：应用编辑页 → “MCP 服务” → 选择已开通服务 → 保存。
|
||||
|
||||
- **不支持的场景**：MCP 服务**不可直接接入千问 API 原生调用链路**（如通过 `dashscope.ChatCompletion.create()` 直接调用），也不支持在 Assistant API 或高代码 SDK 中透传使用——仅限百炼控制台构建的智能体/工作流应用内生效。
|
||||
- **工作流应用（Workflow）**：
|
||||
需显式拖入 **MCP 节点**，手动指定目标服务、具体工具（如 `maps_weather`）、输入参数映射（如将变量 `city` 映射为工具参数 `location`）及输出结果提取规则。适用于确定性、强编排逻辑的任务。
|
||||
|
||||
- **Managed Agents（托管智能体运行时）**：
|
||||
MCP 服务作为可选能力挂载至 Agent 实例，在沙箱环境中与内置工具（`bash`/`read`/`write` 等）协同执行。调用过程通过事件流（`tool_call` / `tool_output`）透出，便于监控与调试。
|
||||
|
||||
- **外部 SDK 或第三方客户端（如 Cherry Studio、Cursor）**：
|
||||
通过百炼提供的 MCP 兼容 endpoint（格式：`https://dashscope.aliyuncs.com/api/v1/mcps/{service-name}/mcp`）直接连接，使用标准 `streamablehttp_client` 客户端调用 `list_tools()` 和 `call_tool()`，无缝对接 OpenAI-style `tools` 接口。
|
||||
|
||||
> ✅ 提示：所有自定义工具（包括原“插件”）必须先发布为 MCP 服务，再在智能体或工作流中添加——平台内不再支持非 MCP 的直连插件。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
| 类别 | 参数名 | 说明 | 开发提示 |
|
||||
|------|--------|------|----------|
|
||||
| **服务标识** | `服务名称` / `描述` | 控制台显示用，不影响调用逻辑；建议命名体现功能（如 `"用户长期记忆"`） | 无需编码配置，仅控制台填写 |
|
||||
| **协议类型** | `type` | 必须与服务端点路径严格匹配：<br>• `"sse"` → 对应 `/sse` 端点<br>• `"streamableHttp"` → 对应 `/mcp` 端点（推荐，百炼默认升级至此） | 错配将触发 `MCP_SERVER_HTTP_METHOD_NOT_ALLOWED`（错误码 `11200058`） |
|
||||
| **远程地址** | `url` | HTTP/SSE 服务地址，要求：<br>• 可公网访问<br>• TLS 证书有效（HTTPS）<br>• 响应头含 `Access-Control-Allow-Origin: *`（若跨域调用） | 自建服务需确保防火墙、SLB 或网关放行对应路径 |
|
||||
| **鉴权凭证** | 环境变量 / KMS 加密凭据 | 敏感字段（如 `AMAP_MAPS_API_KEY`）**禁止明文填写**，必须通过百炼控制台的 KMS 加密存储或环境变量注入 | 使用 `KMS_SECRET_NAME` 引用加密凭据，避免硬编码 |
|
||||
| **部署命令**（自定义服务） | `command` / `args` | `npx` 或 `uvx` 启动时必需：<br>`"npx"` + `["-y", "@modelcontextprotocol/server-memory"]` | Python 服务请优先选用 `uvx`，Node.js 推荐 `npx` |
|
||||
MCP 服务的配置分为元信息、部署、协议端点、安全四类，核心字段如下：
|
||||
|
||||
> ⚠️ 注意：自定义 MCP 服务运行于函数计算（FC），**无法访问本地文件、硬件设备或未授权的私有数据库**；如需连接云数据库，请配置 FC 的 VPC 网络或 IP 白名单。
|
||||
| 类别 | 字段 | 说明 | 示例值 |
|
||||
|------|------|------|--------|
|
||||
| **服务元信息** | `服务名称`、`描述` | 仅用于控制台标识，不影响调用逻辑 | `"高德地图"`、`"提供地理编码与路线规划"` |
|
||||
| **部署配置** | `安装方式` | 启动方式：`npx`（Node.js）、`uvx`（Python）、`http`（远程 SSE） | `"npx"` |
|
||||
| | `部署模式` | `基础模式`（按次计费，有冷启动延迟）或 `极速模式`（常驻计费，低延迟） | `"极速模式"` |
|
||||
| | `部署地域` | 函数计算 FC 托管地域，影响网络延迟 | `"北京"` |
|
||||
| **协议端点** | `type` | 必须与后端严格匹配：`"sse"` 对应 `/sse`，`"streamableHttp"` 对应 `/mcp` | `"streamableHttp"` |
|
||||
| | `url` | 远程地址（HTTP 模式）或本地命令配置（stdio 模式） | `"https://your-server/mcp"` 或 `{ "command": "npx", "args": ["@mcp/server-memory"] }` |
|
||||
| **安全与鉴权** | `KMS 凭据` | 所有敏感参数（如 API Key、Secret）**必须**通过 KMS 加密，禁止明文填写 | — |
|
||||
| | `DASHSCOPE_API_KEY` | 百炼平台认证凭证，调用方必需提供 | `"sk-xxx"` |
|
||||
|
||||
> ⚠️ 注意：`Object` 类型输入参数在 `GET` 请求下不支持，仅 `POST` 允许；子属性必须显式定义，否则发布失败（错误码 `130022`）。
|
||||
|
||||
## 面向开发者的实用建议
|
||||
|
||||
- **优先使用官方服务**：开通即用，免部署、免运维。访问 [MCP 广场](https://bailian.console.aliyun.com/?tab=mcp#/mcp-market) 一键启用 Amap Maps、[长期记忆](long-term-memory.md)等服务。
|
||||
- **调试技巧**：开启智能体「调试模式」可查看完整工具调用请求/响应日志，验证 `type` 与 `url` 是否匹配、参数是否被正确序列化。
|
||||
- **自定义服务快速验证**：本地启动 `@modelcontextprotocol/server-memory` 后，用 `curl https://your-server.com/mcp/tools` 测试工具发现接口是否返回标准 JSON Schema。
|
||||
- **计费提醒**：官方服务有免费额度（如联网搜索 2000 次/月），自定义服务按调用时长计费（基础模式 0.000156 元/秒），建议在工作流中设置超时与重试策略。
|
||||
- **兼容性注意**：百炼已全面升级至 Streamable HTTP（`/mcp`），旧版 SSE（`/sse`）仍兼容但逐步淘汰；新项目请统一使用 `type: "streamableHttp"`。
|
||||
- **快速起步**：优先使用 [MCP 广场](https://bailian.console.aliyun.com/?tab=mcp#/mcp-market) 中的官方服务（如 Amap Maps、WebSearch、QuickChart），开通即用，部分限时免费。
|
||||
- **自建服务**：推荐使用 `npx @mcp/server-memory` 或 `uvx @mcp/server-memory` 快速启动本地 MCP Server；生产环境建议通过 AI 网关封装现有 RESTful API，或通过 OpenAPI 开发者门户将阿里云产品（OSS/ECS）一键发布为 MCP 服务。
|
||||
- **调试技巧**：在智能体调试窗口发送语义明确指令（如 `查询上海浦东机场实时天气`），观察是否触发 `tool_call` 事件；工作流中启用“节点日志”查看完整输入/输出。
|
||||
- **权限准备**：确保主账号或 RAM 子账号已授权服务关联角色 `AliyunServiceRoleForSFMAccessCloudAPI`，子账号还需 `ram:CreateServiceLinkedRole` 权限。
|
||||
- **版本管理**：MCP 服务更新后需重新测试并发布，已关联的应用不会自动生效；删除服务将导致所有关联应用立即失效（不可逆）。
|
||||
|
||||
MCP 不绑定特定模型，但推荐使用 `qwen-max`、`qwen-plus` 等具备强工具调用与多步规划能力的模型以获得最佳效果。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [model context protocol](../guides/model-context-protocol.md)
|
||||
- [start using](../guides/start-using.md)
|
||||
- [application support](../guides/application-support.md)
|
||||
- [plug in](../guides/plug-in.md)
|
||||
- [llm application](../guides/llm-application.md)
|
||||
- [managed agents api](../api/managed-agents-api.md)
|
||||
- [managed agents](../guides/managed-agents.md)
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
# 多模态
|
||||
|
||||
多模态（Multimodal）指模型能够同时理解、生成或关联两种及以上类型的数据模态（如文本、图像、音频、视频、3D几何、结构化数据等），并在此基础上完成跨模态对齐、推理与协同生成。在百炼平台中，多模态不是单一模型能力，而是贯穿文本、视觉、音视频、3D等全栈AI服务的统一设计范式——既体现为原生支持多模态输入/输出的VL（Vision-Language）、VA（Voice-Audio）、V3D（Vision-3D）等联合模型，也体现为通过标准化API协议实现的跨模态工作流编排能力。
|
||||
|
||||
## 在百炼平台的不同场景中，这个概念如何使用
|
||||
|
||||
- **多模态理解（Multimodal Understanding）**：以 `qwen3.7-plus`、`qwen3-vl-plus`、`qwen3.5-omni-plus` 为代表，支持单次请求中混合输入文本 + 图像（最多16张）、视频（最长2小时）、音频、PDF/OCR内容，并统一输出结构化JSON或自然语言响应。例如：上传一张产品图+一段需求描述，直接生成带规格参数的电商文案；上传会议录像+字幕文件，输出带时间戳的摘要与决策点。
|
||||
|
||||
- **多模态生成（Multimodal Generation）**：覆盖图像、视频、3D三大生成域，均以“多模态输入驱动单模态输出”为典型模式：
|
||||
- **文+图 → 图**：`qwen-image-3.0-pro` 支持 `messages` 中同时传入文本提示与图像URL（`{"role": "user", "content": [{"type": "text", "text": "..." }, {"type": "image_url", "image_url": "https://..."}]}`），实现精准图文混控；
|
||||
- **文+图 → 视频**：`wan2.7-t2v-*` 和 `vidu/viduq3-ad_reference2video` 允许 `input.media` 数组中混合 `text`, `image_url`, `first_frame`, `reference_image` 等多种类型，实现“文字定调 + 参考图控风格 + 首帧定构图”的三重约束；
|
||||
- **文+图 → 3D**：`Tripo/Tripo-H3.1` 的 `input` 字段可灵活切换为纯文本（`prompt`）、单图（`image`）或多图数组（`images`），系统自动识别输入模态并路由至对应生成子流程。
|
||||
|
||||
- **多模态编排（Multimodal Orchestration）**：通过百炼“无限画布”低代码工作流或 SDK 自定义链路，将不同模态模型串联为端到端管道。例如：`ASR → Qwen-VL图文理解 → Wan2.7-图像生成 → Pixverse-视频超清`，各节点间自动转换数据格式（语音→文本→图像→视频），开发者无需手动解析中间产物。
|
||||
|
||||
- **多模态交互（Multimodal Interaction）**：`qwen3.5-omni-plus-realtime` 等实时模型支持 WebRTC 音视频流 + 文本消息同步输入，实现边说话、边传图、边打字的真·多模态对话，适用于智能硬件、远程协作等场景。
|
||||
|
||||
> ⚠️ 注意：并非所有模型都原生支持多模态输入。例如 `wan2.6-t2i` 仅支持纯文本输入（T2I），而 `qwen-image-3.0-pro` 才是其多模态升级版。调用前请确认模型文档中标注的 `input` 类型支持范围。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
- **统一输入结构 `input`**：
|
||||
多模态模型要求 `input` 字段采用结构化对象而非扁平字符串。通用格式为：
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": "请将这张图转为线稿风格"},
|
||||
{"type": "image_url", "image_url": "https://example.com/photo.jpg"},
|
||||
{"type": "audio_url", "audio_url": "https://example.com/voice.mp3"}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
各模态字段名固定（`text`/`image_url`/`audio_url`/`video_url`/`file_token`），不可自定义别名。
|
||||
|
||||
- **必需请求头**：
|
||||
- `X-DashScope-Async: enable`：所有耗时 >3s 的多模态生成任务（图像/视频/3D）必须启用异步模式；
|
||||
- `Content-Type: application/json`：严格要求 JSON 格式，不支持 `multipart/form-data`；
|
||||
- `Authorization: Bearer $DASHSCOPE_API_KEY`：API Key 必须与业务空间地域一致（如北京地域需用华北2的Key）。
|
||||
|
||||
- **模型选择约束**：
|
||||
- 模型ID必须精确匹配（含版本后缀），例如 `qwen-image-3.0-pro` ≠ `qwen-image-2.0-pro`；
|
||||
- 多模态能力仅存在于明确标注“VL”、“Omni”、“Pro”、“3.0+”等后缀的模型，旧版模型（如 `wan2.5-i2i-preview`）不支持混合输入。
|
||||
|
||||
- **输入限制（硬性）**：
|
||||
| 模态 | 限制 | 说明 |
|
||||
|------|------|------|
|
||||
| 图像URL | ≤20MB，公网可访问，格式 JPG/PNG | 不支持本地文件或私有OSS直传（需先上传至公开CDN） |
|
||||
| 视频URL | ≤500MB，H.264编码，MP4/WebM | `qwen3.7-plus` 视频理解支持最长2小时，但生成类模型（如 `happyhorse-1.1-t2v`）仅支持≤10秒输入 |
|
||||
| 多图输入 | `images` 数组长度=4（Tripo多图生3D），或 0–14 张（Vidu参考生图） | 缺失视角必须填 `{}` 占位，不可省略 |
|
||||
|
||||
- **输出控制**：
|
||||
- `parameters.watermark: false`：关闭水印（部分模型默认开启）；
|
||||
- `parameters.format: "glb"` / `"mp4"` / `"png"`：显式指定输出格式（若模型支持多格式）；
|
||||
- `parameters.texture: false` & `pbr: false`：Tripo模型中用于返回无贴图基础网格（`base_model_url`）。
|
||||
|
||||
## 面向开发者，简洁实用
|
||||
|
||||
- ✅ **第一步：选对模型** —— 查阅 [模型体验指南](guides/model-experience.md) 中“视觉理解”“多模态生成”章节，认准 `qwen3-vl-*`、`qwen-image-3.0-pro`、`qwen3.5-omni-plus` 等标识；
|
||||
- ✅ **第二步：构造标准 input** —— 始终用 `messages[].content[]` 数组承载多模态元素，按 `type` 区分，勿拼接字符串；
|
||||
- ✅ **第三步：强制异步** —— 所有生成类多模态请求必须加 `X-DashScope-Async: enable`，同步调用会直接报错；
|
||||
- ✅ **第四步：处理长链路** —— 异步任务返回 `task_id` 后，轮询 `GET /api/v1/tasks/{task_id}`，成功响应中的 `output.results[0].xxx_url` 即为结果地址（注意有效期：图片24h，3D模型2h，视频72h）；
|
||||
- ❌ **避坑提醒**：不要复用文本模型的 `input.prompt` 字段调用多模态模型；不要在 `wan2.6-t2i` 上尝试传 `image_url`；不要跨地域混用 API Key 与 WorkspaceId。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [image generation](../api/image-generation.md)
|
||||
- [3d generation](../api/3d-generation.md)
|
||||
- [video generation api](../api/video-generation-api.md)
|
||||
- [model experience](../guides/model-experience.md)
|
||||
- [use cases](../guides/use-cases.md)
|
||||
- [release notes](../guides/release-notes.md)
|
||||
|
||||
|
||||
@@ -1,63 +1,65 @@
|
||||
# OpenAI 兼容接口
|
||||
|
||||
OpenAI 兼容接口是百炼平台提供的一组标准化 API 接入层，遵循 OpenAI 官方 REST API 协议规范（如 `/chat/completions`、`/responses`、`/embeddings` 等路径），使开发者能直接复用现有 OpenAI SDK（如 `openai==1.0+`）、工具链（LangChain、LlamaIndex）或客户端（Cursor、Dify、Hermes Agent），无需修改业务逻辑即可调用千问（Qwen）及第三方大模型。
|
||||
OpenAI 兼容接口是百炼平台提供的一组标准化 REST API，严格遵循 OpenAI 官方 API 协议（v1.0+），支持使用标准 OpenAI SDK（如 `openai>=1.0.0`）直接调用千问（Qwen）及第三方大模型，实现零代码迁移、快速验证与生产集成。
|
||||
|
||||
## 在百炼平台的不同场景中，这个概念如何使用
|
||||
## 在百炼平台的不同场景中如何使用
|
||||
|
||||
- **快速迁移存量应用**：已有基于 OpenAI SDK 的 Python/Node.js 项目，只需替换 `base_url` 和 `api_key`，即可零代码改造接入 Qwen 系列模型（如 `qwen3.7-plus`），适用于试点验证或轻量级生产部署。
|
||||
- **智能体（Agent）开发**：通过 `compatible-mode/v1/responses` 接口调用内置工具能力（联网搜索、网页提取、代码解释器），自动管理对话历史，适合构建无需自维护会话状态的轻量级智能体。
|
||||
- **多模态与专项任务**：按需选用兼容子接口——`/vision/chat/completions`（Qwen-VL/QVQ 图像理解）、`/embeddings`（文本向量化）、`/files` + `/batches`（文档解析与批量推理），各接口共用统一鉴权与配额体系。
|
||||
- **跨框架集成**：支持 LangChain 的 `ChatOpenAI`、LlamaIndex 的 `OpenAIEmbedding` 等原生类，也兼容 Cursor、Cherry Studio、Dify（按量付费方案）等客户端，降低工具链切换成本。
|
||||
- **应用层调用**：在调用已发布的智能体或工作流时，可选 `Responses API` 路径（`/apps/{APP_ID}/compatible-mode/v1/responses`），复用 OpenAI 消息格式，但需注意其不支持 `session_id`，必须显式传入完整 `messages` 历史。
|
||||
|
||||
> ⚠️ 注意：OpenAI 兼容接口是协议层抽象，**不等于模型能力完全对齐**。例如标准 `/chat/completions` 不支持工具调用；`/responses` 仅限 `qwen3-*` 系列；`/embeddings` 不支持多模态模型（如 `qwen3-vl-embedding`）。
|
||||
- **快速迁移现有项目**：已有基于 OpenAI SDK 的应用（如 LangChain、LlamaIndex、Cursor、Dify HTTP 节点等），只需替换 `base_url` 和 `model` 参数，无需修改业务逻辑即可接入 Qwen、DeepSeek、Kimi、GLM 等模型。
|
||||
- **[多模态](multi-modal.md)统一接入**：除文本生成（`/chat/completions`）外，还支持视觉理解（`/vision/completions`）、向量嵌入（`/embeddings`）、批量推理（`/batch`）、会话管理（`/conversations`）和[文件处理](file-processing.md)（`/files`）等能力，均复用同一套 OpenAI 风格请求结构。
|
||||
- **开发与调试提效**：配合 Postman、cURL 或百炼 CLI，可快速验证模型行为；支持流式响应（`stream: true`）、token 统计（`stream_options={"include_usage": true}`）和错误码标准化（如 `400` 参数错误、`429` 限流、`401` 凭证无效）。
|
||||
- **生产环境部署**：推荐使用**业务空间专属域名**（如 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`），获得更高吞吐、更低延迟与独立流量隔离；避免使用已弃用的 `dashscope.aliyuncs.com` 域名。
|
||||
- **跨方案适配**：[Token](token.md) Plan、Coding Plan 和按量计费方案均提供对应 Base URL（如 `https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`），但 API Key 不互通，需严格匹配方案与地域。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
| 参数 | 说明 | 百炼特有约束 |
|
||||
|------|------|--------------|
|
||||
| `base_url` | 必填。服务端点，决定地域、计费方案与 SLA | - 业务空间专属：`https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1`（推荐，99.9% SLA）<br>- [Token](token.md) Plan：`https://token-plan.{region}.maas.aliyuncs.com/compatible-mode/v1`<br>- 按量付费旧域名（不推荐）：`https://dashscope.aliyuncs.com/compatible-mode/v1` |
|
||||
| `model` | 必填。模型 ID，严格区分大小写与版本号 | - `/chat/completions`：支持 `qwen3.7-plus`、`deepseek-v4-pro`、`glm-5.2` 等（不含 `qwen-audio`）<br>- `/responses`：**仅限 `qwen3-*` 系列**（如 `qwen3.7-flash`），不接受 `qwen-plus`<br>- 模型名需与 `base_url` 所属计费方案匹配（如 `qwen3.8-max-preview` 仅 [Token](token.md) Plan 可用） |
|
||||
| `messages` | 必填（除 `/completions`）。标准 OpenAI 格式：`[{ "role": "user/system/assistant", "content": "..." }]` | - `system` 消息被支持，但部分模型（如 `qwen-coder-turbo`）可能忽略<br>- 多轮对话需显式传递全部历史（`/responses` 不自动维护会话） |
|
||||
| `stream` | 可选。启用流式响应（SSE） | - 流式中 `tool_calls` 可能分片，需按 `index` 和 `id` 合并<br>- 异步调用（`background=true`）不支持流式 |
|
||||
| `stream_options` | 可选。控制流式行为 | `{"include_usage": true}` 可在末尾 chunk 返回 token 统计（所有兼容接口均支持） |
|
||||
| `temperature` / `top_p` | 可选。采样控制 | - `temperature` 范围：`[0.0, 2.0)`（非 OpenAI 的 `[0, 2]`）<br>- 二者互斥，建议只设其一<br>- `qwen3.8-max-preview` 思考模式下 `temperature` 下限为 `0.6`（低于自动修正） |
|
||||
| `max_tokens` | 可选。响应长度上限 | 仅截断输出，**不影响模型实际生成长度**；超限内容将被静默丢弃 |
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `model` | string | 是 | 模型标识符，如 `qwen3.7-plus`、`text-embedding-v4`、`qwen-vl-plus`；命名需与所选方案支持列表一致（如 [Token](token.md) Plan 中 `kimi-k2.6` 需写为 `kimi-k2-6`） |
|
||||
| `base_url` | string | 是 | 服务端点，**必须使用业务空间专属域名或方案专用域名**；各地域格式不同（北京：`{WorkspaceId}.cn-beijing.maas.aliyuncs.com`；美国：`dashscope-us.aliyuncs.com`） |
|
||||
| `api_key` | string | 是 | 百炼 API Key，建议通过环境变量 `DASHSCOPE_API_KEY` 设置，禁止硬编码 |
|
||||
| `messages` | array | 是（Chat 接口） | 标准 OpenAI 格式：`[{ "role": "user", "content": "..." }]`；Anthropic 兼容模式下不适用 |
|
||||
| `input` | string / array | 是（Embedding/Rerank） | 向量化输入支持字符串、字符串数组或文件 URL；Rerank 输入需按模型要求组织（如 `qwen3-rerank` 要求 `query` 与 `documents` 平级） |
|
||||
| `temperature` / `top_p` | number | 否 | 控制生成多样性，范围 `0.0–1.0`（OpenAI 兼容接口限制）；二者建议只设其一 |
|
||||
| `max_tokens` | integer | 否 | 限制输出长度，超限自动截断（不影响模型内部生成） |
|
||||
| `stream` | boolean | 否 | 启用流式响应，默认 `true`；搭配 `stream_options={"include_usage": true}` 可在末尾返回 token 使用统计 |
|
||||
| `stop` | string / array | 否 | 指定终止字符串，可用于敏感词拦截或格式控制 |
|
||||
| `seed` | integer | 否 | 设置随机种子（`0–2^31−1`），获得确定性输出 |
|
||||
| `dimensions` | integer | 否（Embedding 特有） | 指定向量维度（仅 `text-embedding-v3/v4`、`qwen3-vl-embedding` 等支持） |
|
||||
| `enable_thinking` | boolean | 否（Qwen3.8+ 特有） | qwen3.8-max-preview 强制启用，OpenAI 兼容接口需通过 `extra_body={"enable_thinking": true}` 传入 |
|
||||
|
||||
## 面向开发者，简洁实用
|
||||
> ⚠️ 注意事项：
|
||||
> - 不支持 `response_format`（如 JSON Schema 强约束），需结构化输出请改用 DashScope 原生接口；
|
||||
> - `tools` 自定义工具仅 DashScope 和 Anthropic 兼容接口支持，OpenAI 兼容-Responses 使用平台预置工具；
|
||||
> - `system` 提示词在 OpenAI 兼容接口中作为 `messages[0]` 的 `role: "system"` 发送，无 token 截断限制（区别于 Anthropic 兼容接口）；
|
||||
> - 所有 OpenAI 兼容接口默认启用流式响应，但工具调用的 `delta.tool_calls` 字段在流式 chunk 中可能不完整，建议非流式模式验证逻辑。
|
||||
|
||||
- ✅ **立即上手**：
|
||||
```python
|
||||
from openai import OpenAI
|
||||
client = OpenAI(
|
||||
api_key="sk-xxx", # 百炼控制台获取
|
||||
base_url="https://your-workspace.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
|
||||
)
|
||||
resp = client.chat.completions.create(
|
||||
model="qwen3.7-plus",
|
||||
messages=[{"role": "user", "content": "你好"}]
|
||||
)
|
||||
print(resp.choices[0].message.content)
|
||||
```
|
||||
## 面向开发者：一句话上手
|
||||
|
||||
- ✅ **关键检查清单**：
|
||||
- ✅ `base_url` 地域、计费方案、WorkspaceId 三者必须一致；
|
||||
- ✅ `model` 名称严格按 [模型市场](https://bailian.console.aliyun.com/#/model-market) 实际列表填写（注意 `-` 与 `_`）；
|
||||
- ✅ 工具调用务必用 `/responses`，不用 `/chat/completions`；
|
||||
- ✅ 流式响应需自行聚合 `delta.tool_calls`，勿依赖单 chunk 完整性；
|
||||
- ❌ 不要混用 [Token](token.md) Plan Key 与按量付费 Key，否则返回 `401 Unauthorized`。
|
||||
安装 SDK → 设置环境变量 → 初始化客户端 → 调用标准方法：
|
||||
|
||||
- ✅ **调试建议**：
|
||||
- 优先使用 `curl` 或 Postman 验证基础请求，排除 SDK 版本兼容问题；
|
||||
- 查看响应头 `X-RateLimit-Remaining` 和 `X-Usage-Token-Count` 监控配额；
|
||||
- 遇到 `429` 错误时，检查 RPM/TPM 限流（按主账号全局统计，含所有子账号与业务空间）。
|
||||
```python
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
api_key=os.getenv("DASHSCOPE_API_KEY"),
|
||||
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
|
||||
)
|
||||
|
||||
# 文本生成
|
||||
resp = client.chat.completions.create(model="qwen3.7-plus", messages=[{"role":"user","content":"你好"}])
|
||||
print(resp.choices[0].message.content)
|
||||
|
||||
# 向量嵌入
|
||||
resp = client.embeddings.create(model="text-embedding-v4", input=["hello world"], dimensions=1024)
|
||||
print(resp.data[0].embedding[:5])
|
||||
```
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [qwen api reference](../api/qwen-api-reference.md)
|
||||
- [get started with models](../guides/get-started-with-models.md)
|
||||
- [toolkits and frameworks](../api/toolkits-and-frameworks.md)
|
||||
- [application call](../api/application-call.md)
|
||||
- [use chat client or development tool](../guides/use-chat-client-or-development-tool.md)
|
||||
- [vector and sort](../api/vector-and-sort.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
# 插件
|
||||
|
||||
插件是百炼平台用于扩展大模型能力的核心机制，通过将外部工具（如 API 服务）安全、标准化地集成到 AI 应用中，弥补大模型在实时检索、精确计算、代码执行、图像生成等场景下的固有局限。每个插件以“工具”为最小可调用单元，由模型基于语义理解自主决策调用时机与参数。
|
||||
|
||||
## 在百炼平台的不同场景中如何使用
|
||||
|
||||
- **智能体（Agent）应用**：在智能体配置页的“插件”区块中添加官方、三方或自定义插件；最多支持同时启用 10 个工具。模型在对话中自动识别用户意图并调用合适插件，结果返回后继续推理生成最终响应。
|
||||
- **工作流（Workflow）应用**：将插件作为独立节点拖入画布，手动编排执行顺序与数据流向（如“搜索 → 解析 → 生成图表”），支持条件分支与参数传递。
|
||||
- **Assistant API 调用**：在请求体 `tools` 字段中声明工具列表（含 `type` 和 `function` Schema），模型根据输入自主选择是否调用及传参；无需显式指令，完全由 LLM 驱动。
|
||||
- **Managed Agents 环境**：不直接使用传统插件，而是通过挂载 MCP（Model Context Protocol）服务接入外部 API，实现与插件能力对等的外部工具调用，适用于需沙箱隔离、多步状态保持的复杂任务。
|
||||
|
||||
> ⚠️ 注意：插件能力仅在指定模型上可用，当前支持 `qwen-turbo`、`qwen-plus`、`qwen-max`、`qwen-vl-plus`、`qwen-vl-max`；`qwen3` 系列模型暂不支持传统插件，但可通过 Managed Agents 的 MCP 方式等效扩展。
|
||||
|
||||
## 关键参数和配置（面向开发者）
|
||||
|
||||
| 参数 | 说明 | 必填 | 示例/约束 |
|
||||
|------|------|------|-----------|
|
||||
| **工具 ID** | 插件内唯一标识符，API 调用时必需字段 | 是 | `"calculator"`、`"text_to_image"` |
|
||||
| **插件 URL + 工具路径**（仅自定义插件） | 构成完整调用地址：`URL + 工具路径` | 是 | `https://api.example.com` + `/v1/search` → `https://api.example.com/v1/search` |
|
||||
| **传参方式** | 决定参数来源：`大模型识别`（从用户输入提取）或 `业务透传`（由外部系统注入） | 是 | 配置为 `biz_params` 或 `user_defined_params` 字段传入 |
|
||||
| **参数类型与校验** | 支持 `String`/`Number`/`Object`；`Object` 类型子属性**不可为空**，需显式定义默认值或必填项 | 是 | `{"query": {"type": "string", "description": "搜索关键词"}}` |
|
||||
| **鉴权配置** | 支持 `Header`（`basic`/`bearer`/`appcode`）或 `Query` 方式；仅允许透传 `Authorization` Header，其他 Header 不支持 | 是 | `Bearer <token>`、`appcode <appcode>`、`?appcode=xxx` |
|
||||
| **HTTP 方法** | 推荐使用 `POST`；若用 `GET`，**禁止输入参数为 `Object` 类型**（否则返回错误码 `130022`） | 建议 | `POST` 更安全、更灵活 |
|
||||
|
||||
## 开发者须知（简洁实用）
|
||||
|
||||
- ✅ **快速起步**：优先选用官方插件（如 `code_interpreter`、`quark_search`），开箱即用，无需配置。
|
||||
- ✅ **自定义接入**：必须提供符合 OpenAPI 3.0 规范的 JSON Schema 描述，模型据此解析参数结构；发布前务必点击“测试工具”验证连通性，并完成“发布”操作。
|
||||
- ✅ **权限准备**：首次使用需主账号授权服务关联角色 `AliyunServiceRoleForSFMAccessCloudAPI`；RAM 用户需额外授予 `ram:CreateServiceLinkedRole` 权限。
|
||||
- ❌ **限制规避**：
|
||||
- `code_interpreter` 沙箱**无网络访问权限**，且依赖库版本固定（如 `pandas==2.2.2`, `requests~=2.31.0`）；
|
||||
- `quark_search` 和 `github_search` 仅返回标题、关键词与摘要，**不支持获取网页/仓库原始内容**；
|
||||
- 删除插件或工具将导致所有已上线应用立即失效，操作不可逆；
|
||||
- 修改插件 URL 或鉴权配置后，必须重新测试并发布全部下属工具。
|
||||
- 🛡️ **安全要求**：所有自定义插件的稳定性、安全性、计费归属均由开发者自行承担；百炼平台仅保障调用链路的协议兼容性与基础转发可靠性。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [plug in](../guides/plug-in.md)
|
||||
- [application support](../guides/application-support.md)
|
||||
- [managed agents](../guides/managed-agents.md)
|
||||
- [managed agents api](../api/managed-agents-api.md)
|
||||
|
||||
|
||||
@@ -1,50 +1,45 @@
|
||||
# Prompt 工程
|
||||
|
||||
Prompt 工程是指在百炼平台上系统性设计、组织、验证与优化提示词（Prompt）的方法论与实践体系，其目标是通过结构化指令、角色设定、上下文注入、样例引导和自动化反馈等手段，显著提升大模型输出的准确性、稳定性、格式一致性与业务适配性。
|
||||
Prompt 工程是指在百炼平台上，通过系统化设计、结构化表达与迭代优化提示词（Prompt），以精准引导大语言模型行为、提升输出稳定性、可控性与业务适配性的技术实践。它不是简单的“写指令”，而是融合角色设定、任务分解、约束注入、样例引导与效果验证的工程化方法论。
|
||||
|
||||
## 在百炼平台的不同场景中，这个概念如何使用
|
||||
## 在百炼平台的不同场景中如何使用
|
||||
|
||||
- **模板化 Prompt 管理**：在「组件管理 > 提示词」中，开发者可基于 ICIO（Input-Context-Instruction-Output）、CRISPE（Capacity-Role-Insight-Statement-Personality-Experiment）或 RASCEF（Role-Action-Steps-Constraints-Examples-Format）等工程框架创建可复用模板；支持 `${variable}` 变量插值，实现跨业务动态填充（如营销文案生成、日志分析摘要），适用于文本生成、图片生成（正向/负向 Prompt 分离配置）等标准化任务。
|
||||
Prompt 工程能力深度集成于百炼三大核心层，开发者可根据需求选择对应路径：
|
||||
|
||||
- **智能体（LLM Application）构建**：在新版智能体（Agent 2.0）中，系统提示词（System Prompt）是 Prompt 工程的核心载体——它定义 Agent 的角色、能力边界、工具调用规范及输出格式约束。结合知识库（RAG）与 MCP 工具，Prompt 工程确保模型在多步推理中保持意图对齐与结构化响应（如始终以 JSON 输出订单状态）。
|
||||
- **模板化开发（推荐用于标准化任务）**
|
||||
使用「Prompt 模板」功能，在控制台或通过 `CreatePromptTemplate` API 创建可复用的提示词资产。支持基于 ICIO、CRISPE、RASCEF 等成熟框架结构化编写（如明确 Role/Task/Format/Constraint），适用于营销文案生成、摘要抽取、JSON 结构化输出等确定性任务。文本与图片生成模板需分别配置（后者需正向/负向 Prompt 分离）。
|
||||
|
||||
- **自动增强与反馈优化**：
|
||||
- **自动优化**：无需人工经验，一键将原始自然语言 Prompt（如“帮我写个产品介绍”）转化为含角色注入、指令强化、安全护栏的工业级版本；不计费，且输入数据不用于训练。
|
||||
- **反馈优化**：面向分类、结构化抽取等高精度任务，上传 5–10 条典型样例（few-shot）与 ≥20 条评测集，平台通过多轮评估-反思-重写，产出业务效果更优的 Prompt，直接支持 A/B 测试与灰度发布。
|
||||
- **智能体应用（Agent）中的动态编排**
|
||||
在 Agent 2.0 应用中，Prompt 工程体现为**系统提示词（System Prompt）的精细化配置**：支持嵌入变量（如 `/user_name`）、绑定知识库检索结果、注入工具调用上下文，并可通过 `enable_thinking=true` 观察模型推理链路。此时 Prompt 是 Agent 的“大脑指令集”，直接影响规划、工具选择与响应质量。
|
||||
|
||||
- **API 与 SDK 集成**：通过 `CreatePromptTemplate` / `GetPromptTemplate` 接口管理模板元数据；渲染后作为 `system` 或 `messages[0].content` 传入 `ChatCompletion` 等模型 API；SDK 自动处理变量注入与地域适配（仅华北2可用），开发者聚焦业务逻辑。
|
||||
- **自动化优化（适合无 Prompt 经验或快速验证）**
|
||||
利用「Prompt 自动优化」服务，输入原始自然语言指令（如“帮我写一封道歉邮件”），平台自动注入角色、明确格式、强化边界（如“不使用感叹号”）、增强安全性，输出更鲁棒的版本；或使用「Prompt 反馈优化」，上传 query-answer 样例对，由 `qwen-max` 等强模型驱动多轮评估，生成带 few-shot 示例和显式约束的高精度 Prompt，特别适用于分类、表格生成等结构化任务。
|
||||
|
||||
> ⚠️ 注意：Prompt 样例库功能已下线，新项目请统一迁移至 RAG 表格库实现上下文增强；所有 Prompt 相关能力（模板、优化、关联）**仅支持华北2（北京）地域**。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
| 参数 | 说明 | 注意事项 |
|
||||
|------|------|----------|
|
||||
| `promptTemplateId` | 模板唯一标识符 | 由平台生成，用于 API 获取模板内容 |
|
||||
| `workspaceId` | 业务空间 ID | 必填，控制台或 `ListWorkspaces` 接口获取，决定资源隔离与鉴权范围 |
|
||||
| `variables` | 模板中声明的变量名列表（JSON 数组） | 最多 64 个；语法为 `${topic}`，不支持嵌套或表达式 |
|
||||
| `enable_thinking`（智能体场景） | 启用规划-执行-反思链路 | 仅对千问-Max 等支持思考模式的模型生效，用于调试 Prompt 效果 |
|
||||
| `top_k` / `score_threshold`（RAG 场景） | 控制检索片段数量与相关性阈值 | 影响 Prompt 中注入的上下文质量，间接决定最终输出可靠性 |
|
||||
| 参数 | 说明 | 开发者须知 |
|
||||
|------|------|------------|
|
||||
| `promptTemplateId` | 模板唯一标识符 | 调用 `GetPromptTemplate` 获取内容后，必须按 `variables` 字段声明的变量名（如 `["topic", "tone"]`）填充值，不可动态增删变量。 |
|
||||
| `workspaceId` | 业务空间 ID | 所有 Prompt API（模板、优化、应用调用）均需显式传入，是资源隔离与权限控制的基础。 |
|
||||
| `has_thoughts` | 是否返回样例召回详情 | 仅在已关联 RAG 表格库的智能体应用中有效；设为 `true` 时，响应中 `thoughts` 字段可查看实际注入的上下文片段，用于调试检索效果。 |
|
||||
| `temperature`（全局） | 输出随机性控制 | 建议 Prompt 驱动的确定性任务（如结构化提取）设为 `0.1–0.3`；创意类任务可放宽至 `0.6–0.8`。该参数作用于模型层，与 Prompt 内容协同生效。 |
|
||||
| 召回片段数（RAG 场景） | 单次注入的上下文片段数量 | 默认 `5`，上限 `10`；增加可提升信息覆盖，但显著增加 [Token](token.md) 成本与延迟，需在控制台或 API 中权衡设置。 |
|
||||
|
||||
> ⚠️ **重要限制**：
|
||||
> - 所有 Prompt 功能**仅支持华北2（北京）地域**；
|
||||
> - 控制台编辑器最大长度 **6144 字符**，实际 token 消耗需按所选模型上下文窗口（如 Qwen-Max 32K）自行校验；
|
||||
> - 图片生成模板暂不支持通过 API 创建（`CreatePromptTemplate` 接口当前仅支持文本类）；
|
||||
> - Prompt 自动优化与反馈优化过程中的用户数据**不存储、不训练、符合阿里云隐私政策**。
|
||||
## 面向开发者的实用建议
|
||||
|
||||
## 面向开发者，简洁实用
|
||||
|
||||
- ✅ **起步建议**：从预置模板（如“会议纪要生成”）开始，复制后修改变量与指令细节，比从零编写更高效；
|
||||
- ✅ **调试技巧**：启用 `enable_thinking=True` + `stream=True`，实时观察模型如何解析 Prompt 并规划步骤；
|
||||
- ✅ **生产最佳实践**：
|
||||
- 对关键业务 Prompt，用反馈优化生成多个候选版本，结合线上评测集（如准确率、格式合规率）择优部署；
|
||||
- 将 Prompt 模板 ID 与变量映射关系纳入配置中心管理，避免硬编码；
|
||||
- 监控 `input_tokens` 增长——优化后的 Prompt 若引入大量样例或知识片段，可能推高成本，需权衡效果与开销。
|
||||
- ❌ **避免踩坑**：勿依赖已下线的 Prompt 样例库功能；新项目统一使用 RAG 表格库或反馈优化替代。
|
||||
- **优先模板化**：将高频、稳定 Prompt 封装为模板（而非硬编码在代码中），便于版本管理、A/B 测试与跨应用复用。
|
||||
- **变量即契约**：模板中 `variables` 是运行时契约——前端/SDK 必须提供完整且类型匹配的值，缺失或错位将导致渲染失败。
|
||||
- **优化≠替代**：自动优化是起点，非终点；产出的 Prompt 应人工校验逻辑完整性与业务合规性，尤其关注安全边界是否被弱化。
|
||||
- **[Token](token.md) 敏感性**：Prompt 内容 + 变量填充后总长度 ≤ 6144 字符；RAG 注入片段数 × 平均片段长度 + Prompt 本身，需严格控制在模型上下文窗口内（如 `qwen3.7-plus` 支持 1M token，但实际应预留 20% 给输出）。
|
||||
- **地域强约束**：若应用部署在其他地域（如华东1），必须将 Prompt 相关逻辑（模板获取、优化调用）路由至 `cn-beijing` 接入点，否则直接报错。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [prompt](../guides/prompt.md)
|
||||
- [llm application](../guides/llm-application.md)
|
||||
- [application component api reference](../api/application-component-api-reference.md)
|
||||
- [application support](../guides/application-support.md)
|
||||
- [llm application](../guides/llm-application.md)
|
||||
- [model experience](../guides/model-experience.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,51 +1,67 @@
|
||||
# 检索增强生成
|
||||
|
||||
检索增强生成（Retrieval-Augmented Generation，RAG）是一种将大语言模型（LLM）的生成能力与外部知识源的精准检索能力相结合的技术范式。它通过在生成前动态检索相关知识片段，并将其作为上下文注入提示词，显著提升模型在事实性、时效性和领域专业性任务上的准确性与可靠性。
|
||||
检索增强生成（Retrieval-Augmented Generation，RAG）是百炼平台的核心能力范式，指在大语言模型生成响应前，先从私有或领域知识库中动态检索相关片段，并将检索结果作为上下文注入提示词，从而提升回答的准确性、事实性与专业性。它不是独立模型，而是一种可复用、可配置、端到端集成的增强架构。
|
||||
|
||||
## 在百炼平台的不同场景中，这个概念如何使用
|
||||
|
||||
在百炼平台，RAG 不是抽象技术概念，而是已封装为开箱即用的核心能力，贯穿多个产品模块：
|
||||
RAG 在百炼中以**知识库（Knowledge Base）**为载体，贯穿多种产品形态和接入路径，开发者可根据业务复杂度与控制粒度需求灵活选用：
|
||||
|
||||
- **知识库（Knowledge Base）**：作为 RAG 的底层基础设施，支持文档、表格、图片、音视频等多模态数据的自动解析、向量化、语义检索与重排。开发者无需部署向量数据库或训练嵌入模型，所有检索逻辑由平台统一托管。
|
||||
- **知识检索与问答（Knowledge API）**：提供 `/search`（纯检索）和 `/chat`（端到端问答）两类接口。前者返回结构化文本切片（chunk），供自定义生成逻辑调用；后者内置规划→工具调用→生成三阶段流式 pipeline，直接输出最终答案。
|
||||
- **智能体与工作流应用（Application）**：在应用配置中一键绑定知识库，启用“必定调用”或“按需触发”模式，RAG 结果自动注入系统提示词（如 `{result}` 占位符），与模型生成无缝协同。
|
||||
- **框架集成（LlamaIndex / Spring AI Alibaba）**：通过官方 SDK 将百炼云端知识库接入主流开发框架，复用 `DashScopeCloudIndex` 或 `DashScopeDocumentRetriever` 等组件，快速构建生产级 RAG 应用。
|
||||
- **多端业务集成（Website / 企业微信 / 钉钉等）**：AppFlow 提供零代码 RAG 接入路径——上传文件 → 创建知识库 → 关联应用 → 发布，即可在网站悬浮窗、企微机器人等渠道获得知识增强的对话体验。
|
||||
- **零代码应用集成**：在智能体或工作流应用中添加「文档知识库」节点，绑定已发布知识库并配置相似度阈值、权重等参数；系统自动完成检索→引用→生成全流程，适用于客服助手、内部知识问答等标准场景。
|
||||
|
||||
- **API 直接调用**：
|
||||
- `knowledge` 服务（`/api/v2/apps/knowledge/chat`）：面向终端用户的端到端问答，强制绑定 `app_id`，返回结构化 SSE 流（`plan` → `tool_call` → `answer`），支持多轮对话与溯源引用；
|
||||
- `application component` API（`Retrieve` 接口）：面向开发者的底层检索能力，可自由组合检索结果与任意模型（如 `qwen3.7-plus`）进行自主生成，适用于需精细控制 RAG 链路的定制化系统。
|
||||
|
||||
- **框架集成**：
|
||||
- **LlamaIndex**：通过 `DashScopeCloudIndex` 构建云端知识库，调用 `as_query_engine()` 自动集成检索与生成，支持 `DashScopeRerank` 后处理；
|
||||
- **Spring AI Alibaba**：使用 `DashScopeDocumentRetriever` 直接对接知识库，配合 `ChatClient` 实现“检索+生成”解耦编排，适合 Java 生态项目。
|
||||
|
||||
- **渠道嵌入场景**：在网站、企业微信、钉钉、微信公众号等渠道通过 AppFlow 接入百炼应用时，启用「必定调用知识库」策略，所有用户提问均自动触发 RAG 增强，无需修改渠道侧逻辑。
|
||||
|
||||
> ⚠️ 注意：所有 RAG 能力仅在中国站华北2（北京）地域可用；知识库必须处于「已发布」状态才参与检索；未发布的草稿或下线知识库不可见。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
RAG 效果可通过以下关键参数精细调控（均在控制台或 API 中显式配置）：
|
||||
RAG 效果高度依赖以下三类可调参数，建议按阶段优化：
|
||||
|
||||
| 参数名 | 作用域 | 类型 | 常用值 | 说明 |
|
||||
|--------|--------|------|--------|------|
|
||||
| `retrieval_top_k` / `top_k` | 知识库、API、框架 | int | `3`–`5`（默认） | 最终送入大模型的检索片段数量（经重排+阈值过滤后）。值过大会增加噪声，过小易丢失关键信息。 |
|
||||
| `similarity_threshold` / `score_threshold` | 知识库、API、应用配置 | float | `0.3`–`0.6` | 过滤低相关性切片的相似度阈值。建议结合业务测试调整，避免漏召或误召。 |
|
||||
| `initial_retrieval_top_k` | 知识库高级设置 | int | `50`（默认） | 向量召回阶段的初步切片数，影响重排成本与精度平衡。降低可节省费用，但可能牺牲长尾召回率。 |
|
||||
| `chunk_size` / `chunk_overlap` | **仅本地 RAG 场景** | int | `512`/`128` | 文档切分粒度与重叠长度，适用于基于百炼 Embedding API 的自建轻量 RAG 方案。 |
|
||||
| `enable_query_rewrite` | 知识库创建时 | bool | `True` | 开启多轮对话改写，自动补全指代（如“它”、“上文提到的”），提升上下文感知能力。 |
|
||||
### 1. 检索阶段（影响召回质量与成本）
|
||||
| 参数 | 说明 | 推荐值 | 备注 |
|
||||
|------|------|--------|------|
|
||||
| `top_k`（向量/关键词召回数） | 控制双路初始召回切片数量 | 20–50 | 默认 50；值越大 Rerank [Token](token.md) 消耗越高，但漏召风险降低 |
|
||||
| `similarity_threshold` | 过滤低于该相似度的切片 | 0.3–0.6 | 过高易漏召，过低引入噪声；建议从 0.45 开始调优 |
|
||||
| `max_retrieve_count` | 最终返回给生成模型的切片总数 | 3–10 | 直接影响 [prompt](../guides/prompt.md) 长度与生成质量，推荐 ≤8 |
|
||||
|
||||
> ⚠️ 注意：所有云端 RAG 能力均**不支持自定义嵌入模型、切分逻辑或向量引擎**，全部依赖百炼托管的向量模型（如 `gte-base` 嵌入 + `gte-rerank` 重排）。
|
||||
### 2. 知识库构建与元数据（影响检索精准度）
|
||||
| 参数 | 说明 | 用法示例 |
|
||||
|------|------|----------|
|
||||
| `Meta信息抽取` | 为文本切片附加结构化上下文（如 `file_name`, `cat_name`, 正则提取字段） | 解决“同名文件内容混杂”问题，支持在 Prompt 中通过 `{meta.file_name}` 引用 |
|
||||
| `标签过滤` | 上传文件时打标（如 `硬件`/`软件`），检索时指定 `tag=硬件` 精确限定范围 | 适用于多业务域隔离场景 |
|
||||
|
||||
### 3. 高级策略（提升多轮体验）
|
||||
| 参数 | 说明 | 注意事项 |
|
||||
|------|------|----------|
|
||||
| `多轮对话改写` | 创建知识库时启用，基于历史对话自动补全当前 Query | 创建后不可修改，建议新知识库默认开启 |
|
||||
| `权重` | 多知识库绑定时分配数值权重（如 `权重=3` > `权重=1`） | 仅对同类型知识库（如均为文档搜索类）生效 |
|
||||
|
||||
## 面向开发者，简洁实用
|
||||
|
||||
- ✅ **快速启动**：控制台创建知识库 → 上传 PDF/DOCX/TXT → 在应用中绑定 → 发布 → 调用 `/chat` 接口，5 分钟完成 RAG 上线。
|
||||
- ✅ **调试优先**：使用 `/search` 接口独立验证检索质量（检查 `score` 和 `content`），再接入生成逻辑，避免混淆检索与生成问题。
|
||||
- ✅ **参数调优口诀**：
|
||||
- 先调 `similarity_threshold` 控制精度（高阈值 = 更严格，低召回）；
|
||||
- 再调 `retrieval_top_k` 平衡信息量与噪声（通常 `3`–`5` 最佳）；
|
||||
- 最后观察 `latency` 和 `response_code` 日志（开通 SLS 监控），定位瓶颈在检索还是生成。
|
||||
- ✅ **避坑提醒**：
|
||||
- `workspaceId` 必须与 API Key 所属业务空间完全一致，不可用 Project ID 替代；
|
||||
- `/chat` 接口不接受 `top_k` 参数，其召回策略由绑定的知识应用配置决定；
|
||||
- 音视频类知识库不支持新增切片，仅支持删除；
|
||||
- 多知识库联合检索需在应用配置中显式设置权重，否则默认等权融合。
|
||||
- ✅ **快速起步**：控制台创建知识库 → 上传 PDF/DOCX/TXT → 发布 → 在智能体应用中绑定 → 启用「必定调用」→ 即可上线。
|
||||
- ✅ **调试技巧**：调用 `/api/v1/indices/knowledge/search` 接口单独测试检索效果，验证 `query` 是否能召回预期切片。
|
||||
- ✅ **成本优化**：优先调小 `top_k` 和 `max_retrieve_count`；启用 `similarity_threshold` 过滤低质切片；避免在 Prompt 中重复粘贴冗余检索结果。
|
||||
- ✅ **错误排查**：
|
||||
- 返回空结果？检查知识库状态是否为「已发布」、`workspaceId` 地域是否为 `cn-beijing`、`query` 是否含敏感词被拒答；
|
||||
- 流式响应中断？确认客户端正确解析 SSE event 类型（`plan`/`tool_call`/`answer`），勿假设单次响应即完成；
|
||||
- 限流 `429`？实现指数退避重试，或升级至旗舰版知识库（支持更高 QPS）。
|
||||
|
||||
RAG 不是黑盒魔法，而是可控的数据增强管道——掌握检索参数、善用元数据、分阶段验证，即可稳定交付高可信 AI 服务。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [knowledge](../api/knowledge.md)
|
||||
- [knowledge base](../guides/knowledge-base.md)
|
||||
- [application component api reference](../api/application-component-api-reference.md)
|
||||
- [frameworks](../api/frameworks.md)
|
||||
- [application use cases](../guides/application-use-cases.md)
|
||||
- [application support](../guides/application-support.md)
|
||||
- [use cases](../guides/use-cases.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,52 +1,49 @@
|
||||
# 流式输出
|
||||
|
||||
流式输出（Streaming Output）是百炼平台提供的一种实时响应机制，允许模型在生成过程中分块（chunk）返回结果，而非等待全部内容完成后再一次性返回。它显著降低端到端延迟，提升用户交互体验，并支持前端实现打字机效果、实时转录、语音合成驱动等增量式渲染场景。
|
||||
流式输出（Streaming Output）是指模型服务在生成响应过程中，将结果以增量方式分块（chunk）实时返回给客户端，而非等待全部内容生成完毕后一次性返回。这种方式显著降低端到端延迟，提升用户感知的响应速度与交互流畅性，是构建低延迟对话、实时语音合成、长文本生成等场景的关键能力。
|
||||
|
||||
## 在百炼平台的不同场景中如何使用
|
||||
|
||||
流式输出在以下核心能力中被统一支持，但协议、事件格式与适用范围存在差异：
|
||||
- **Qwen 系列模型 API（OpenAI 兼容 / DashScope 原生）**：
|
||||
默认启用流式输出（`stream: true`），适用于 `qwen-max`、`qwen-plus`、`qwen-turbo` 等文本生成模型。[OpenAI 兼容接口](openai-compatible-interface.md)返回符合 SSE 标准的 `text/event-stream` 响应；DashScope 原生接口支持更细粒度控制（如 `incremental_output` 参数）。注意：OpenAI 兼容-Responses 模式下，流式 chunk 中 `delta.tool_calls` 字段可能不完整，建议非流式模式验证工具调用逻辑。
|
||||
|
||||
- **知识问答（`/api/v2/apps/knowledge/chat`）**：通过 Server-Sent Events（SSE）协议返回 `text/event-stream` 响应，按阶段输出 `planning` → `tool_calling` → `generation` 三类事件，每个事件携带结构化字段（如 `event: generation`, `data: {"text": "..."}`），需客户端正确解析 `data:` 前缀与换行分隔。
|
||||
- **应用调用（Application Call）**：
|
||||
仅**同步调用**支持流式输出（通过 `stream=true` 启用），适用于新版智能体、旧版智能体及工作流；**异步调用（`background=true`）不支持流式输出**，必须轮询或订阅事件获取最终结果。
|
||||
|
||||
- **智能体/工作流调用（Responses API）**：在同步调用接口（如 `/responses`）中设置 `stream=true`，返回符合 OpenAI 兼容格式的 SSE 流，每 chunk 包含 `delta.content`（增量文本）、`finish_reason` 等字段；**异步调用（`background=true`）不支持流式输出**。
|
||||
- **Omni Realtime API 与 Realtime API**：
|
||||
原生基于 WebSocket 的事件驱动架构，天然支持流式输出。文本以 `response.text.delta` 事件逐 token 推送；音频以 `response.audio.delta` 事件按 PCM 帧（通常 20ms/帧）持续下发。`modalities: ["text", "audio"]` 配置下，两类流可并行、低延迟同步输出。
|
||||
|
||||
- **Realtime API（AOQ/WebRTC/WebSocket）**：基于长连接的双向事件流，非传统 HTTP SSE。服务端通过 `response.delta`（文本增量）、`response.audio.delta`（音频 PCM 片段）、`conversation.item.input_audio_transcription.delta`（ASR 实时识别）等事件主动推送，客户端需监听并拼接。
|
||||
|
||||
- **Omni Realtime API（WebSocket）**：采用自定义 WebSocket 事件协议，关键事件包括 `response.delta`（文本流）、`response.audio.delta`（音频流）、`response.done`（结束标识）。支持 `incremental_output=true` 进一步确保每次只返回新生成 token，避免重复内容。
|
||||
|
||||
- **通用应用调用（DashScope API）**：`/api/v1/apps/{APP_ID}/completion` 接口本身**不原生支持流式输出**；如需流式能力，必须使用 Responses API 兼容路径（即 `compatible-mode/v1/responses`）并显式启用 `stream=true`。
|
||||
|
||||
> ✅ 统一原则：所有流式能力均要求客户端具备事件解析、缓冲管理与错误重连能力；不支持流式的调用（如[异步任务](asynchronous-task.md)、DashScope 原生 completion）将返回完整 JSON 响应体。
|
||||
- **异步任务类模型（图像/视频生成等）**：
|
||||
**不支持流式输出**。此类任务需通过 `task_id` 轮询或事件总线接收完成通知，结果为一次性结构化响应（如 OSS URL 或 base64 图片）。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
| 参数 | 类型 | 作用 | 是否必需 | 说明 |
|
||||
|------|------|------|----------|------|
|
||||
| `stream` | `boolean` | 启用流式响应模式 | 否（默认 `false`） | 所有支持流式的接口均需显式设为 `true`；设为 `false` 或不传则返回完整响应 |
|
||||
| `incremental_output` | `boolean` | 启用真正增量式输出（仅 `stream=true` 时生效） | 否（默认 `false`） | 若为 `true`，每个 chunk 的 `delta.content` 仅含本次新生成内容（非累计）；若为 `false`，部分场景可能重复返回已发送内容，前端需自行去重 |
|
||||
| `modalities` | `string[]` | 指定输出模态（Realtime/Omni 场景） | 是（当含 `"audio"` 时） | 必须包含 `"text"`；若需语音合成，需同时指定 `"audio"` 并配置 `voice` |
|
||||
| `turn_detection.type` | `string` | VAD 检测模式（Realtime/Omni） | 否（默认 `"server_vad"`） | 影响流式触发时机：`"semantic_vad"` 可实现语义级断句流式，`"server_vad"` 依赖音频静音检测 |
|
||||
| 参数 | 类型 | 说明 | 适用场景 |
|
||||
|------|------|------|----------|
|
||||
| `stream` | `boolean` | 控制是否启用流式响应。设为 `true` 时，HTTP 响应头为 `Content-Type: text/event-stream`，响应体为 SSE 格式 chunk。默认值为 `false`（同步阻塞模式）。 | Qwen API、Application Call（同步） |
|
||||
| `incremental_output` | `boolean` | DashScope 原生接口特有参数，启用后返回增量 token（等效于 `stream=true`），但响应格式为 JSON 数组而非 SSE。适用于无法处理 SSE 的客户端。 | DashScope 文本生成原生接口 |
|
||||
| `modalities` | `array` | 指定输出模态组合，如 `["text"]` 或 `["text","audio"]`。决定流式事件类型（`response.text.delta` / `response.audio.delta`）。 | Omni Realtime API、Realtime API |
|
||||
| `enable_search` / `tools` | `boolean` / `array` | 影响流式内容结构：启用后，流式响应中会包含 `response.tool_use.delta` 或 `response.search_result.delta` 等事件，需客户端按事件类型解析。 | Omni Realtime（`qwen3.5-omni-realtime` 系列）、Qwen DashScope 接口 |
|
||||
|
||||
> ⚠️ 注意事项：
|
||||
> - `stream=true` 时，HTTP 响应头必须包含 `Content-Type: text/event-stream`（SSE）或维持 WebSocket/AOQ 长连接；
|
||||
> - 流式响应无 `Content-Length`，客户端不可依赖该 header 判断结束；
|
||||
> - 超时时间需延长（建议 ≥60s），避免因网络波动中断连接；
|
||||
> - 错误发生时，服务端会发送 `error` 事件（SSE）或 `error` WebSocket message，需捕获处理。
|
||||
> - 流式响应需客户端正确处理 SSE 解析（如 `EventSource` 或 `aiohttp.ClientSession` 的 `content.iter_any()`）；
|
||||
> - 所有流式接口均要求连接保持活跃，超时断连将中断输出；
|
||||
> - 异步调用、文件上传、[多模态](multi-modal.md)预处理等前置步骤**本身不支持流式**，仅最终模型推理阶段可流式。
|
||||
|
||||
## 面向开发者：简洁实用建议
|
||||
|
||||
- **前端渲染**：对 `stream=true` + `incremental_output=true` 的响应，直接追加 `delta.content` 到 DOM 即可，无需缓存或去重；若未启用 `incremental_output`，请维护本地 buffer 并比对上一 chunk 内容。
|
||||
- **错误处理**：监听 `event: error`（SSE）或 `error` message（WebSocket），检查 `data.code` 和 `data.message`，常见错误如 `429 Too Many Requests`（需指数退避）、`503 Service Unavailable`（重试）。
|
||||
- **调试技巧**：使用 `curl -N` 或浏览器 DevTools Network → EventStream 查看原始 SSE 数据；WebSocket 场景可用 `wscat` 工具连接测试。
|
||||
- **性能优化**：Realtime/Omni 场景下，优先选用 `semantic_vad` + `incremental_output=true` 组合，可最小化首包延迟（TTFT）与生成延迟（TPOT）。
|
||||
- **兼容性提醒**：旧版 DashScope 原生 API（如 `/completion`）不支持流式，请务必切换至 Responses API 兼容路径。
|
||||
- ✅ **首选流式**：对延迟敏感场景（如客服对话、语音助手），务必设置 `stream=true` 并监听增量事件；
|
||||
- ✅ **验证兼容性**：OpenAI SDK 默认支持 SSE，但需确认版本 ≥1.0；自定义 HTTP 客户端请严格遵循 [SSE 协议规范](https://html.spec.whatwg.org/multipage/server-sent-events.html)；
|
||||
- ✅ **错误处理**：流式请求失败时，部分 chunk 可能已接收，需检查 `event: error` 或 `data:` 中的 `error` 字段，并重试完整请求；
|
||||
- ❌ **避免混用**：不要在 `background=true` 的异步请求中设置 `stream=true`（会被忽略）；
|
||||
- 🛠️ **调试技巧**：使用 `curl -N` 或 Postman 的 SSE 插件直接观察原始流式响应，快速定位解析问题。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [knowledge](../api/knowledge.md)
|
||||
- [qwen api reference](../api/qwen-api-reference.md)
|
||||
- [application call](../api/application-call.md)
|
||||
- [application support](../guides/application-support.md)
|
||||
- [realtime api user guide](../api/realtime-api-user-guide.md)
|
||||
- [omni realtime api](../api/omni-realtime-api.md)
|
||||
- [realtime api user guide](../api/realtime-api-user-guide.md)
|
||||
- [more about models](../api/more-about-models.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,37 +1,54 @@
|
||||
# Token
|
||||
|
||||
Token 是百炼平台中用于计量大模型输入、输出及内部计算资源消耗的核心计费与性能单位。它代表模型处理的最小语义单元（如中文字符、英文子词或图像 patch），其数量直接决定调用成本、推理延时和资源配额使用。
|
||||
Token 是百炼平台中用于计量模型输入、输出及内部计算资源消耗的最小语义单位，由模型 tokenizer 对原始文本、图像、语音等[多模态](multi-modal.md)内容进行分词/编码后生成。它是平台计费、配额控制、性能监控与资源调度的核心基础单元，所有模型调用（含推理、工具调用、[多模态](multi-modal.md)生成）均以 Token 用量为依据进行 Credits 扣减或资源占用核算。
|
||||
|
||||
## 在百炼平台的不同场景中，这个概念如何使用
|
||||
|
||||
- **Token Plan 订阅服务**：Token 是 Credits 消耗的基础单位。一次调用的总 Credits =（输入 Token 数 + 输出 Token 数）× 模型单价系数 + 思考模式/缓存/工具调用等附加因子。例如 `qwen3.6-plus` 的输入/输出 Token 均按固定单价折算，视觉理解或多模态生成中图片被编码为视觉 Token 后同样计入总量。
|
||||
- **Token Plan 订阅服务**：Token 是 Credits 消耗的基本粒度。实际扣费 = `input_tokens × 输入单价 + output_tokens × 输出单价 + 工具调用附加费用`；不同模型（如 `qwen3.8-max-preview` vs `wan2.7-image`）、不同模式（标准/思考/缓存命中）对应不同单价，且[多模态](multi-modal.md)模型（图像/视频/语音）需通过 Skill/Agent 独立接口调用，其 Token 计算逻辑与文本模型独立。
|
||||
|
||||
- **高吞吐推理（TPM 预留 / 快速模式）**：Token 直接决定容量单位（kTPM = 1000 tokens/分钟）。TPM 预留按输入/输出 Token 分别配额；快速模式虽无显式 TPM 配额，但受全局 TPM 排队约束，且返回结构中 `usage.completion_tokens_details.reasoning_tokens` 显式分离“思考 Token”，全部计入总输出 Token 计费。
|
||||
|
||||
- **模型监控（Model Monitoring）**：Token 消耗是核心可观测指标之一。监控系统按分钟级或小时级聚合 `input_tokens` 和 `output_tokens`，支持按 API Key、模型、时间范围统计用量趋势，并可配置“Token 消耗突增”类告警。`max_tokens` 参数显式限制输出长度，直接影响 Token 成本与首 Token 延时。
|
||||
- **模型部署（PTU / MU / LoRA）**：
|
||||
- PTU 模式下，`ptu_capacity.input_tpm/output_tpm` 以 Token/分钟为单位定义专属吞吐；长输入（如 >32K）可能触发阶梯系数（如 ×1.33），影响实际 Token 消耗核算；
|
||||
- MU 模式支持 `enable_thinking`，启用后模型内部推理过程产生的中间 Token（如思维链）同样计入 `output_tokens`；
|
||||
- LoRA 微调模型仅支持按 Token 用量计费，不支持 PTU/MU 的性能配置能力。
|
||||
|
||||
- **应用监控（Application Monitoring）**：在智能体或工作流链路中，每个 `LLM` 节点的 Span 明确记录 `Token总量`（输入 + 输出之和），`EMBEDDING` 节点则以 Token 等效长度衡量文本向量化开销。该数据用于定位高 Token 消耗环节（如冗长 [prompt](../guides/prompt.md) 或过长响应），支撑成本优化与链路调优。
|
||||
|
||||
- **高性能推理（TPM / Fast Mode）**：Token 是容量与吞吐的标尺。TPM 预留以 **kTPM（千 Token/分钟）** 为单位购买专属算力；Fast Mode 则以 **TPS（Token/秒）** 衡量实际输出速率。缓存命中时，部分 Token 可享受折扣（如 `glm-5.2` 缓存部分按 25% 折算），进一步降低有效 Token 成本。
|
||||
- **监控与可观测性**：
|
||||
- 模型监控中，`prompt_tokens`、`completion_tokens`、`cached_tokens` 等字段在单次请求日志中精确回传，是成本分析与性能归因的关键依据；
|
||||
- 应用观测中，每个 `LLM` Span 的 `token_count` = `input_tokens + output_tokens`，支持按节点、按 Trace 维度聚合分析 Token 分布，辅助优化提示工程与 Agent 设计。
|
||||
|
||||
## 关键参数和配置
|
||||
|
||||
- `max_tokens`：强制限制模型输出最大 Token 数，推荐生产环境必设，防止意外长响应导致成本失控和超时。
|
||||
- `temperature` / `top_p` 等采样参数：间接影响输出 Token 分布与长度稳定性，但不改变 Token 计数逻辑。
|
||||
- 缓存相关：启用缓存后，重复输入的 Token 可按模型策略（如 25% 折扣）折算用量，需在控制台开通并确认模型支持。
|
||||
- 多模态 Token：图像/视频/语音输入经编码器转换为视觉/音频 Token，统一纳入计费；具体换算规则由模型实现决定（如 `qwen-image-2.0-pro` 对 1024×1024 图片生成约 1280 视觉 Token）。
|
||||
- **Token 计算来源**：严格依赖所调用模型自身的 tokenizer（如 Qwen 使用 `QwenTokenizer`，GLM 使用 `GLMTokenizer`），不同模型对同一输入的 Token 数可能差异显著。开发者应通过 `usage` 字段获取实际值，不可自行估算。
|
||||
|
||||
- **缓存相关字段**（若支持）：
|
||||
- `usage.prompt_tokens_details.cached_tokens`：命中前缀缓存的输入 Token 数，按折扣价计费（如 GLM-5.2 缓存命中部分按 25% 折算）；
|
||||
- `usage.completion_tokens_details.cached_tokens`：暂未开放，当前仅输入侧支持缓存计量。
|
||||
|
||||
- **思考 Token 显式暴露**（仅限支持思考模式的模型）：
|
||||
- `usage.completion_tokens_details.reasoning_tokens`：模型内部推理步骤产生的 Token，计入总 `completion_tokens`，不可减免；
|
||||
- `usage.completion_tokens_details.generated_tokens`：最终返回给用户的 Token 数，二者之和等于 `completion_tokens`。
|
||||
|
||||
- **长输入阶梯系数**（PTU/高并发场景）：当 `prompt_tokens` 超出基础区间（如 32K），平台按预设系数放大计费 Token 数（如 `32K–200K` 区间系数为 1.33），具体阈值与系数见各模型文档。
|
||||
|
||||
## 面向开发者，简洁实用
|
||||
|
||||
- ✅ **始终显式设置 `max_tokens`**：避免无上限输出，控制成本与延迟。
|
||||
- ✅ **监控 `input_tokens` 和 `output_tokens` 分离值**：识别 [prompt](../guides/prompt.md) 过长或响应冗余问题（如 `output_tokens / input_tokens > 5` 可能提示低效生成）。
|
||||
- ✅ **多模态调用前预估 Token**：使用 SDK 的 `count_tokens()` 工具或参考文档中的典型值（如单图 ≈ 1000–2000 Token），避免额度误判。
|
||||
- ❌ **不要假设 Token 数 = 字符数**：中文、emoji、特殊符号、代码块均按子词（subword）或视觉 patch 计数，实际值需以 API 返回的 `usage` 字段为准。
|
||||
- ⚠️ **Token Plan 与通用 API 的 Token 计费独立**：同一模型在不同接入方式（如 `token-plan.cn-beijing.maas.aliyuncs.com` vs `dashscope.aliyuncs.com`）下 Token 单价与配额互不影响。
|
||||
- ✅ **必查字段**：每次成功调用后，务必解析响应中的 `usage` 对象，提取 `prompt_tokens`、`completion_tokens` 及细分字段（如 `cached_tokens`、`reasoning_tokens`），用于成本核对与异常诊断。
|
||||
|
||||
- ✅ **避免估算**：不要基于字符数或单词数粗略换算 Token —— 使用 `dashscope.Tokenizer` SDK 或调用 `/v1/tokenize` 接口（支持主流模型）获取准确值。
|
||||
|
||||
- ✅ **监控对齐**：若发现控制台用量统计与 API 返回 `usage` 不一致，优先检查是否开通「推理日志」（模型监控）或「应用观测」（应用监控）—— 未开通时，控制台仅显示小时级聚合数据，存在 1–2 小时延迟。
|
||||
|
||||
- ⚠️ **地域约束牢记**：Token Plan 专属 API Key（`sk-sp-`）仅在华北2（北京）生效；TPM 预留与快速模式支持北京/新加坡双地域；而推理日志与高级监控能力仅在北京/新加坡/弗吉尼亚可用。
|
||||
|
||||
- ⚠️ **计费不可逆**：Token 消耗实时发生，无退款机制。高频调用前建议先用小样本验证 Token 用量，尤其注意多模态输入（如 Base64 图片）和思考模式带来的隐性开销。
|
||||
|
||||
## 关联主题页
|
||||
|
||||
- [token plan guide](../guides/token-plan-guide.md)
|
||||
- [model high speed inference](../guides/model-high-speed-inference.md)
|
||||
- [model deployment 1](../guides/model-deployment-1.md)
|
||||
- [model monitoring](../guides/model-monitoring.md)
|
||||
- [application monitoring](../guides/application-monitoring.md)
|
||||
- [model high speed inference](../guides/model-high-speed-inference.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,84 +1,57 @@
|
||||
# application evaluation
|
||||
|
||||
应用评测是百炼平台用于系统化评估智能体或工作流应用输出质量的核心能力，支持自动评分与人工标注双轨并行。它通过评测集提供标准化输入数据，结合评估器（LLM 或 Code）实现多维度自动打分，并允许开发者配置标签进行主观判断与深度归因分析，最终生成可量化的评测报告与调优建议。
|
||||
application evaluation 是阿里云百炼平台用于系统化评估智能体、工作流等应用输出质量的核心能力，涵盖自动评测、手动评测、评测集管理、评估器与标签体系四大模块。它支持从数据准备、任务执行到结果分析的全链路质量保障，既可通过大模型实现端到端自动评分与归因，也支持人工标注与规则化校验，适用于研发迭代、上线验证与持续监控等场景。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **评测类型**：当前支持三类评测集——**智能体**、**工作流**和**自定义**，分别适配不同应用形态的出入参结构 [新版评测集](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/new-version-of-evaluation-set.md)；同时保留传统分类：**对话分析**（用于人工评测）和**知识问答**（用于自动评测）[评测集](../../raw/application-user-guide/application-evaluation/application-evaluation-dataset.md)。
|
||||
|
||||
- **评估器类型**：支持预置模板（如“问答相关性”“格式校验”）及自定义创建，包括：
|
||||
- **LLM评估器**：基于 `qwen-max` 或 `qwen-plus` 等大模型进行语义评分，适用于相关性、幻觉、有害性等复杂判断；
|
||||
- **Code评估器**：通过 Python 脚本执行精确规则匹配（如 JSON 校验、关键词存在性），零 [Token](../concepts/token.md) 成本；
|
||||
- **基于评测任务的评估器**：从已完成人工标注的历史任务中自动提炼评分逻辑 [评估器](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/grader.md)。
|
||||
- **自动评测**：基于知识库自动生成评测集，支持单应用深度诊断与最多 8 个应用的横向对比，依赖 `qwen-max` 或 `qwen-plus` 模型生成评测集及执行评分 [自动评测](../../raw/application-user-guide/application-evaluation/application-auto-evaluation.md)。
|
||||
- **手动评测**：通过人工构建 Excel 格式评测集（`.xls`/`.xlsx`），结合人工打标完成效果评估，适用于需强业务语义判断的场景 [手动评测](../../raw/application-user-guide/application-evaluation/evaluate-manual-application.md)。
|
||||
- **新版评测任务**：统一支持智能体、工作流与自定义应用类型，可灵活组合 LLM 评估器与 Code 评估器进行多维度自动评分，并同步支持人工标签标注 [评测任务](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/evaluation-task.md)。
|
||||
- **评估器体系**：提供预置模板（如相关性、格式校验）及自定义能力，LLM 评估器适用于语义理解类评测，Code 评估器适用于精确规则匹配，二者可共存于同一任务中 [评估器](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/grader.md)。
|
||||
- **标签管理**：支持分类、布尔值、数字、文本四类标签，用于人工标注与数据筛选，既可用于评测任务，也可直接应用于应用观测中的 Span 数据标注 [标签管理](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/label-management.md)。
|
||||
|
||||
- **评测模式**：
|
||||
- **自动评测**：面向已发布且配置知识库的智能体应用，支持单应用深度诊断与最多 8 个应用的横向对比 [自动评测](../../raw/application-user-guide/application-evaluation/application-auto-evaluation.md)；
|
||||
- **手动评测**：依赖人工构建 `.xls`/`.xlsx` 评测集，通过“打标”完成人工评分，适用于高专业性场景；
|
||||
- **新版评测任务**：统一入口，支持“不关联应用”（纯人工标注）、智能体或工作流调用，并可混合使用多个评估器与标签 [评测任务](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/evaluation-task.md)。
|
||||
|
||||
> **注意**：文档 1 和文档 4 对评测集类型的定义存在差异——文档 1 仅提“对话分析”与“知识问答”，而文档 4 明确扩展为“智能体/工作流/自定义”三类。实际平台以文档 4 的新版分类为准，旧分类（如“对话分析”）属于“智能体”类型下的具体数据结构变体，非独立类型。
|
||||
> **注意**：文档 3 与文档 4 对评测集类型的定义存在差异——文档 3 将评测集分为“对话分析”和“知识问答”两类，而文档 4 引入了“智能体”“工作流”“自定义”三类结构化类型。实际使用中应以新版控制台（文档 4、5、6、7）为准，旧版“知识问答”对应新版“智能体”类型评测集，“对话分析”则需通过“自定义”类型并手动配置字段实现。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **评测集字段要求**：
|
||||
- 智能体类评测集：必含 `Prompt`（用户输入）与 `Completion`（参考答案）字段；若含多轮对话，需 `SessionId` 字段对齐会话上下文；
|
||||
- 知识问答类（`.jsonl`）：必含 `query`、`referenceAnswer`、`coarseKeywords`、`fineKeywords`；
|
||||
- 自定义评测集：字段完全由用户定义，但需在评估器参数映射时确保字段名一致。
|
||||
|
||||
- **评估器配置核心项**：
|
||||
- `评分范围`（如 `0-1`、`1-5`、`0-100`）：决定输出粒度，影响阈值敏感性；
|
||||
- `通过阈值`：默认设为范围中值（如 `0-1` 时阈值为 `0.5`），用于 Pass/Fail 判定；
|
||||
- `参数映射`：必须将评估器 Prompt 中引用的变量（如 `query`, `response`, `reference`）一一映射至评测集字段或应用输出，**未完成映射则无法保存评测任务**。
|
||||
|
||||
- **评测规则控制**：
|
||||
- 分类采样数：在自动评测中，可为“事实型”“分析型”等任务类型分别设置采样数量；
|
||||
- 模型选择：生成评测集与执行评测均限选 `qwen-max` 或 `qwen-plus`；
|
||||
- 标签类型：支持分类、布尔值、数字、文本四类，用于人工标注维度 [标签管理](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/label-management.md)。
|
||||
- **评测集字段要求**：不同评估器对字段有硬性依赖。例如，使用“问答相关性”预置评估器时，评测集必须包含 `query` 和 `response` 字段；若映射为 `Prompt`/`Completion`，需在参数映射中显式指定 [评估器](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/grader.md)。
|
||||
- **模型选择限制**：
|
||||
- 自动评测的评测集生成与最终评分阶段均仅支持 `qwen-max` 和 `qwen-plus` [自动评测](../../raw/application-user-guide/application-evaluation/application-auto-evaluation.md)；
|
||||
- 新版 LLM 评估器支持更广模型范围，但具体可用模型需在创建时下拉选择，且部分模型限时免费。
|
||||
- **采样与权重**：自动评测中可通过滑块设置各任务类型（事实型、分析型等）的采样数；新版评测任务支持为每个评估器独立配置评分范围（如 0–1 或 1–5）与通过阈值。
|
||||
- **[Token](../concepts/token.md) 消耗预估**：所有涉及模型调用的操作（生成评测集、执行评测、运行 LLM 评估器）均显示“预估平均消耗”与“预估最大消耗”，前者为参考值，后者为成本硬上限，实际用量以账单为准 [自动评测](../../raw/application-user-guide/application-evaluation/application-auto-evaluation.md)。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **准备数据**：
|
||||
- 创建评测集：可手动上传 `.xls`/`.xlsx`（对话分析）或 `.jsonl`（知识问答），或使用新版“智能体/工作流”类型自动生成模板；亦支持从应用观测导入真实流量数据 [新版评测集](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/new-version-of-evaluation-set.md)。
|
||||
- 发布评测集：草稿状态不可用于评测，必须点击“发布”后方可选用。
|
||||
1. **准备评测数据**：
|
||||
- 自动生成：在自动评测流程中，基于已配置的知识库，使用 `qwen-max`/`qwen-plus` 生成 `.jsonl` 格式知识问答评测集；
|
||||
- 手动上传：按模板准备 `.xls`/`.xlsx`（对话分析）或 `.jsonl`（知识问答）文件，或使用新版“智能体”类型评测集，系统根据所选应用出入参自动生成表结构 [评测集](../../raw/application-user-guide/application-evaluation/application-evaluation-dataset.md)；
|
||||
- 从应用观测导入：将线上真实请求-响应数据直接导入评测集，提升评测真实性 [新版评测集](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/new-version-of-evaluation-set.md)。
|
||||
|
||||
2. **配置评测任务**：
|
||||
- 进入[评测任务](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/efm/app_evaluate/tabs?activeKey=task)页面，选择评测集版本与目标应用（智能体/工作流/不关联）；
|
||||
- 添加评估器（最多 10 个），严格完成所有参数映射；
|
||||
- 可选添加标签（如“回答完整性”“是否存在幻觉”），用于人工补充判断。
|
||||
2. **创建评测任务**：
|
||||
- 旧版自动评测：依次完成“创建任务→设置评测集→配置规则→执行评测”四步流程，支持试运行验证；
|
||||
- 新版评测任务：在任务创建页选择评测集、关联应用（智能体/工作流/不关联）、添加评估器（最多 10 个）并完成参数映射，再配置人工标签 [评测任务](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/evaluation-task.md)。
|
||||
|
||||
3. **执行与分析**：
|
||||
- 启动评测后，状态变为“评测中”，完成后可在“数据明细”页查看每条样本的评估器评分与人工标签；
|
||||
- “指标统计”页提供综合得分仪表盘、各评估器通过率柱状图及 BadCase 分布；
|
||||
- 自动评测额外提供归因分析（如“检索无效”“切片不完整”），并给出对应优化建议 [自动评测](../../raw/application-user-guide/application-evaluation/application-auto-evaluation.md)。
|
||||
- 自动评测完成后，报告包含总正确率、BadCase 归因（如“检索无效”“切片不完整”）、RAG 分项得分及调优建议；
|
||||
- 新版任务支持在“数据明细”页查看各评估器评分与人工标签，在“指标统计”页查看综合得分、通过率柱状图及数据分布。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **权限与前提**：
|
||||
- 子账号需具备 `管理员` 或 `应用评测-操作` 权限；
|
||||
- 自动评测要求应用已发布、配置知识库、且开通“应用观测”功能；
|
||||
- 多应用横向评测时，所有被选应用必须共享至少一个知识库。
|
||||
|
||||
- **技术限制**：
|
||||
- 评测集单文件 ≤ 20 MB，单次上传 ≤ 10 个文件；
|
||||
- 评测任务创建后**不可修改**应用、评测集或评估器配置，仅支持新增标签 [评测任务](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/evaluation-task.md)；
|
||||
- 基于评测任务创建的评估器**不支持试运行**，需在真实任务中验证效果 [评估器](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/grader.md)。
|
||||
|
||||
- **计费与消耗**：
|
||||
- LLM评估器调用产生 [Token](../concepts/token.md) 费用，Code评估器无额外成本；
|
||||
- 预估 [Token](../concepts/token.md) 消耗为参考值，实际用量以账单为准；“预估最大消耗”为硬性上限，实际极少达到 [自动评测](../../raw/application-user-guide/application-evaluation/application-auto-evaluation.md)。
|
||||
|
||||
- **数据一致性**：
|
||||
- 若选用已有评测集进行自动评测，需确保其 `referenceAnswer` 和 `keywords` 内容均可在当前指定知识库中检索到，否则评测结果失真；
|
||||
- 新版评测任务中，“不关联应用”选项适用于纯人工标注场景，此时系统不会触发任何模型调用。
|
||||
- **应用状态要求**：自动评测仅支持**已发布**且**已配置知识库**的智能体应用；手动评测与新版评测任务虽支持未发布应用，但“智能体”类型评测集仍要求应用处于发布状态方可关联调用 [自动评测](../../raw/application-user-guide/application-evaluation/application-auto-evaluation.md)。
|
||||
- **权限与观测依赖**：子账号需具备 `管理员` 或 `应用评测-操作` 权限；自动评测强制依赖 `应用观测` 功能开通并添加目标应用至观测列表，评测期间关闭观测将导致失败或结果不准 [自动评测](../../raw/application-user-guide/application-evaluation/application-auto-evaluation.md)。
|
||||
- **评测集版本与引用约束**：评测集发布后生成新版本，创建任务时可指定版本；已发布的评测集若被评测任务引用，则无法删除 [新版评测集](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/new-version-of-evaluation-set.md)。
|
||||
- **配置不可变性**：评测任务创建后，其关联的评测集、应用、评估器映射等核心配置不可修改，如需调整须新建任务 [评测任务](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/evaluation-task.md)。
|
||||
- **评估器试运行限制**：基于历史评测任务创建的评估器不支持试运行，需在实际任务中验证效果 [评估器](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/grader.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [评测集](../../raw/application-user-guide/application-evaluation/application-evaluation-dataset.md)
|
||||
- [自动评测](../../raw/application-user-guide/application-evaluation/application-auto-evaluation.md)
|
||||
- [手动评测](../../raw/application-user-guide/application-evaluation/evaluate-manual-application.md)
|
||||
- [评测集](../../raw/application-user-guide/application-evaluation/application-evaluation-dataset.md)
|
||||
- [新版评测集](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/new-version-of-evaluation-set.md)
|
||||
- [评测任务](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/evaluation-task.md)
|
||||
- [标签管理](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/label-management.md)
|
||||
- [评估器](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/grader.md)
|
||||
- [标签管理](../../raw/application-user-guide/application-evaluation/new-version-of-application-evaluation/label-management.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,76 +1,59 @@
|
||||
# application monitoring
|
||||
|
||||
应用监控（Application Monitoring）是阿里云百炼平台提供的端到端可观测能力，用于追踪智能体、工作流及高代码类应用的内部执行链路，覆盖向量生成、知识检索、大模型调用等关键节点，并采集延时、[Token](../concepts/token.md) 用量、状态码等核心指标。数据同步频率为分钟级，支持按 Trace ID / Span ID / Request ID 快速定位问题，适用于性能分析、成本优化与线上评测样本构建。该功能当前仅提供控制台界面，**暂无公开 API 接口**，详见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md)。
|
||||
应用观测（Application Monitoring）是阿里云百炼平台提供的端到端可观测能力，用于追踪智能体、工作流及高代码类应用的内部执行链路，支持查看调用延时、[Token](../concepts/token.md)消耗、模型思考过程及各节点状态。所有数据以分钟级频率同步至可观测链路 OpenTelemetry 服务，当前**不提供 API 接口**，仅通过控制台使用。详细背景与设计目标见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md)。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **支持的应用类型**：智能体应用、工作流应用、高代码应用（但高代码应用仅上报 `CHAIN` 根节点，[不支持内部链路追踪](../../raw/application-user-guide/application-monitoring/application-observation.md)）。
|
||||
- **不支持的应用**：通过 Assistant API 创建的智能体应用（见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md) 中的明确限制说明）。
|
||||
- **支持的应用类型**：智能体应用（Single Agent）、工作流应用（Workflow）和高代码应用（Rich Code），但**不支持通过 Assistant API 创建的智能体应用**（详见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md)）。
|
||||
- **可观测节点类型**：
|
||||
- 基础节点：`CHAIN`（根节点，名称如 `AgentApp`/`WorkflowApp`/`FullCodeApp`）、`LLM`、`RETRIEVER`（含 `TextRetriever`/`VectorRetriever`）、`EMBEDDING`、`RERANKER`、`REWRITER`；
|
||||
- 工作流专属节点：`START`、`API`、`CLASSIFIER`、`CONDITION`、`FUNCTION_COMPUTE`、`END`；
|
||||
- 安全与扩展节点：`TOOL`（[插件](../concepts/plugin.md)调用）、`GUARDRAIL`（绿网内容审核）；
|
||||
- 注意：`KnowledgeRetriever` 下的子节点（如 `TextRetriever`）才实际触发可观测行为；[长期记忆](../concepts/long-term-memory.md)中的检索**暂不支持观测**（参见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md) 附录说明）。
|
||||
- `CHAIN`（根节点，如 `AgentApp`/`WorkflowApp`/`FullCodeApp`）
|
||||
- `LLM`（大模型调用，含输入/输出 [Token](../concepts/token.md) 统计与首 [Token](../concepts/token.md) 耗时）
|
||||
- `RETRIEVER`（含 `TextRetriever` 和 `VectorRetriever`，默认返回 100 个切片）
|
||||
- `EMBEDDING`、`RERANKER`、`REWRITER`、`TOOL`、`GUARDRAIL`、`API`、`CLASSIFIER` 等工作流专用节点
|
||||
- `START`/`END`（工作流生命周期节点）
|
||||
- **核心功能**：调用链追踪（Trace/Spans）、多维筛选（按状态、Span Name、输入/输出关键词、延时、Token 量、标签等）、数据导出（JSONL/Excel）、监控统计（调用次数、失败率、Token 趋势、平均延时）、Span 数据一键导入评测集、以及支持布尔/分类/数字/文本四类数据标注。
|
||||
|
||||
> **注意**：文档中对 `FullCodeApp` 的描述存在隐含矛盾——正文称“目前不支持追踪其内部调用链路”，但附录表格又将其列为高代码应用的 `CHAIN` 节点类型。实际行为以控制台表现为准：高代码应用仅上报顶层 `CHAIN` Span，无嵌套子 Span。此为功能限制，非文档错误。
|
||||
> **注意**：高代码应用虽可开启观测，但 `FullCodeApp` 节点为黑盒，**不支持展开其内部调用链路**；实际可观测性依赖开发者在代码中集成 AgentScope-AI 的 Tracing 模块并启用 `--telemetry enable` 参数（参见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md) 中“常见问题”部分）。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数名 | 含义 | 说明 |
|
||||
|--------|------|------|
|
||||
| `Trace ID` | 全局唯一调用链标识 | 用于跨节点关联同一请求的完整生命周期 |
|
||||
| `Span ID` | 单个操作单元唯一标识 | 每个节点（如 `LLM`、`RETRIEVER`）对应一个 Span ID |
|
||||
| `Request ID` | 应用层请求标识 | 通常由百炼网关生成，与用户侧请求强绑定 |
|
||||
| `延时（ms）` | 节点执行耗时 | `LLM` 节点延时包含流式响应首 [Token](../concepts/token.md) 及全文生成时间；`平均首Token耗时` 仅在流式场景下统计 |
|
||||
| `Token总量` | 输入 [Token](../concepts/token.md) + 输出 Token 总和 | `EMBEDDING` 节点 Token 量指向量化输入长度；`LLM` 节点指模型侧总 Token 数 |
|
||||
| `状态` | 执行结果 | `正常` 或 `错误`（错误可进一步细分为 `ManualIntervention`/`SystemIntervention` 等） |
|
||||
|
||||
所有字段均支持在 Span 列表页通过**过滤器**进行条件筛选（如“延时 > 5000”、“输出包含‘拒绝’”），也支持导出为 JSONL 或 Excel 进行离线分析。
|
||||
| 参数 | 说明 | 备注 |
|
||||
|------|------|------|
|
||||
| **Request ID / Trace ID / Span ID** | 用于精准定位单次调用或子链路 | 可在节点详情页点击“查看 ID”获取 |
|
||||
| **延时（ms）** | LLM 节点延时包含完整响应过程（含流式首 Token 时间）；整体应用延时为 Chain 根节点耗时 | “平均首 Token 耗时”仅对流式调用有效 |
|
||||
| **Token 总量** | = 输入 Token + 输出 Token（LLM 节点）；Embedding 节点 Token 量仅指向量化输入长度 | 所有 Token 统计均基于对应模型 tokenizer 计算 |
|
||||
| **状态** | `正常` 或 `错误`（后者可进一步按错误类型细分） | 错误类型需结合日志与节点上下文诊断 |
|
||||
| **标签（Label）** | 支持布尔、分类、数字、文本四类标注，与评测集标签系统共享 | 单个评测集最多支持 50 个字段映射 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **前提配置（一次性）**
|
||||
首次使用需完成三项授权与开通：
|
||||
- 授权可观测链路 OpenTelemetry 服务角色权限；
|
||||
- 开通可观测链路 OpenTelemetry 服务；
|
||||
- 初始化 OpenTelemetry 存储 LogStore。
|
||||
> 主账号操作分钟级生效；子账号需额外配置 `AliyunBailianFullAccess` + `应用观测-操作` 页面权限 + `CreateServiceLinkedRole` 系统策略（详细步骤见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md)）。
|
||||
1. **前提配置**（首次使用必做）：
|
||||
- 主账号或已授权子账号访问 [应用观测](https://bailian.console.aliyun.com/tab=app?tab=app#/app-observe)，点击右上角 **应用观测配置**；
|
||||
- 完成三步：授权 OpenTelemetry 服务角色 → 开通 OpenTelemetry 服务 → 初始化 LogStore 存储（主账号开通通常分钟级生效；子账号需额外配置 `CreateServiceLinkedRole` 权限，详见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md)）。
|
||||
|
||||
2. **启用观测**
|
||||
- 进入 [应用观测](https://bailian.console.aliyun.com/tab=app?tab=app#/app-observe)，点击 **选择被观测的应用** → **添加**；
|
||||
2. **启用观测**：
|
||||
- 在应用观测页面点击 **选择被观测的应用** > **添加**；
|
||||
- 应用必须已**发布**且属于当前业务空间；
|
||||
- 添加后自动开始分钟级数据同步；关闭观测则停止同步（历史数据保留，新增数据不再采集）。
|
||||
- 添加后自动开始分钟级数据同步；关闭观测则停止同步，重开仅保留新增数据。
|
||||
|
||||
3. **查看与分析**
|
||||
- 在 Span 列表页，支持三种视图模式：`Root Span`（默认）、`All Span`（平铺所有节点）、`Model Span`（仅含 `LLM` 节点）；
|
||||
- 单击节点名称展开详情，查看原始输入/输出、标注记录、嵌套子 Span；
|
||||
- 支持按时间范围（最长 30 天）、聚合粒度（分钟/小时/天）查看**监控统计**页签中的趋势图（调用次数、失败率、Token 总量、平均延时等）。
|
||||
3. **查看与分析**：
|
||||
- 在 Span 列表页切换筛选模式（`Root Span`/`All Span`/`Model Span`）；
|
||||
- 使用过滤器组合条件（如 `状态=错误 AND 延时>5000`）；
|
||||
- 点击节点名称展开详情，查看原始数据、标注记录、嵌套子节点；
|
||||
- 在 **监控统计** 页签按时间范围（最长 30 天）与粒度（分钟/小时/天）查看趋势图。
|
||||
|
||||
4. **高级操作**
|
||||
- **导出数据**：Trace 列表页右上角 → 导出 JSONL 或 Excel；
|
||||
- **添加到评测集**：批量选中 Span → 映射字段（最多 50 个）→ 追加或覆盖导入；
|
||||
- **数据标注**：支持布尔值、分类、数字、文本四类标签，与评测集标签系统共享。
|
||||
4. **扩展操作**：
|
||||
- **导出数据**：Trace 列表页右上角支持 JSONL/Excel 导出；
|
||||
- **添加到评测集**：批量选择 Span，映射字段后追加或覆盖已有评测集；
|
||||
- **数据标注**：在节点详情页点击 **数据标注**，复用统一标签体系。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **功能限制**：
|
||||
- 当前**无 API 接口**，全部操作依赖控制台（见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md) 明确声明）；
|
||||
- 不支持 Assistant API 创建的智能体应用；
|
||||
- 高代码应用仅上报 `FullCodeApp` 根节点，无法观测内部[函数调用](../concepts/function-calling.md)或自定义逻辑；
|
||||
- [长期记忆](../concepts/long-term-memory.md)（Long-term Memory）检索过程不可观测；
|
||||
- `TextRetriever`/`VectorRetriever` 默认返回 100 个切片，数量不可配置。
|
||||
|
||||
- **数据时效性**：
|
||||
- 数据同步延迟为**分钟级**，不适用于毫秒级实时告警场景；
|
||||
- 监控统计图表支持最长 30 天历史数据查询，超出范围不可回溯。
|
||||
|
||||
- **计费说明**：
|
||||
- 应用监控功能本身**不收取额外费用**；
|
||||
- 所有追踪数据存储于可观测链路 OpenTelemetry 服务，按该服务标准计费（详见 [计费说明](https://help.aliyun.com/zh/arms/tracing-analysis/product-overview/untitled-document-1697525445039)）。
|
||||
|
||||
- **权限与部署要求（高代码应用）**：
|
||||
- 必须在代码中集成 AgentScope-AI 的 `Tracing` 模块；
|
||||
- 部署时需显式添加 `--telemetry enable` 参数，否则无任何数据上报（见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md) 常见问题）。
|
||||
- **无 API 支持**：当前仅提供控制台界面，无法通过 SDK 或 HTTP API 集成（明确声明于 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md)）。
|
||||
- **存储与计费**：应用观测功能本身免费，但底层依赖 OpenTelemetry 服务，产生的 Trace 数据存储与查询费用需单独承担（参见 [计费说明](../../raw/application-user-guide/application-monitoring/application-observation.md)）。
|
||||
- **高代码应用限制**：`FullCodeApp` 节点不可展开，内部逻辑不可见；必须显式集成 AgentScope-AI Tracing 模块并部署时启用 `--telemetry enable`，否则无数据上报。
|
||||
- **知识库检索盲区**：`KnowledgeRetriever` 下的 `TextRetriever`/`VectorRetriever` 可观测，但**[长期记忆](../concepts/long-term-memory.md)（Long-term Memory）中的检索过程暂不支持观测**。
|
||||
- **权限要求**：子账号需同时具备 `AliyunBailianFullAccess`、页面级“应用观测-操作”权限及 `ram:CreateServiceLinkedRole` 权限，缺一不可（详细配置步骤见 [应用观测](../../raw/application-user-guide/application-monitoring/application-observation.md)）。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,51 +1,47 @@
|
||||
# application permission management
|
||||
|
||||
百炼平台的权限管理以“业务空间”为最小单元，提供跨地域、多角色、细粒度的模型调用、调优、部署及控制台页面访问控制。权限体系分为超级管理员、业务空间管理员和普通用户三类角色，分别对应全局管理、单空间管理和资源使用能力。所有 API Key 的行为均继承其归属业务空间的模型权限策略，与用户账号的控制台权限解耦。
|
||||
百炼平台的权限管理以“业务空间”为最小管理单元，支持基于角色（超级管理员、业务空间管理员、普通用户）的多维度控制，覆盖模型调用/调优/部署、页面访问、API Key 管理及 OpenAPI 接口调用等核心场景。权限策略与地域强绑定，且默认业务空间不具备精细化限流与模型管控能力，需通过新建业务空间实现隔离与治理。详细设计与约束请参见 [权限管理](../../raw/application-user-guide/application-permission-management/application-permission-management-overview.md)。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
权限管理覆盖以下核心能力：
|
||||
- **模型调用**：控制特定模型在业务空间内是否可通过控制台或 OpenAPI 调用，并支持 QPM（每分钟请求数）和 [Token](../concepts/token.md) 限流；默认业务空间不支持此限制 [原文标题](../../raw/application-user-guide/application-permission-management/application-permission-management-overview.md)。
|
||||
- **模型调优（训练）**：控制是否允许在业务空间内进行模型微调（Fine-tuning），以及调优后是否允许部署；默认业务空间对所有支持调优的模型开放该能力 [原文标题](../../raw/application-user-guide/application-permission-management/application-permission-management-overview.md)。
|
||||
- **模型部署**：控制是否允许直接部署基础模型（如 Qwen 系列）至业务空间；默认业务空间无限制。
|
||||
- **控制台页面权限**：按菜单粒度（如“模型体验”“批量推理”“模型观测”等）授予 RAM 用户访问和操作权限；该设置**不影响 API Key 行为**。
|
||||
- **API Key 管理**：支持为 RAM 用户授权创建、删除、查看某业务空间下全部 API Key 的能力；单个 API Key 绑定唯一地域+业务空间+用户，不可迁移 [原文标题](../../raw/application-user-guide/application-permission-management/application-permission-management-overview.md)。
|
||||
|
||||
> **注意**：文档中多次强调“默认业务空间无法设置模型调用/调优/部署限制”，但未明确定义何为“默认业务空间”。实践中指用户首次开通百炼服务时自动创建的初始空间（通常命名含 `default` 或无显式名称），其权限策略不可编辑，需新建业务空间实现精细化管控。
|
||||
- **模型级控制**：支持对单个模型配置调用、调优（训练）、部署三类权限，每类权限可独立开关。
|
||||
- **资源维度**：支持模型请求 QPM 限流、[Token](../concepts/token.md) 限流；支持知识库、[Prompt 工程](../concepts/prompt-engineering.md)、[长期记忆](../concepts/long-term-memory.md)等应用能力的 OpenAPI 访问控制。
|
||||
- **空间粒度**：所有权限均按“地域 + 业务空间”两级生效，跨地域业务空间完全隔离，互不影响。
|
||||
- **用户角色**：
|
||||
- 超级管理员（主账号或拥有 `AliyunBailianFullAccess` 的 RAM 用户）可跨空间管理模型、用户、API Key 及限流策略；
|
||||
- 业务空间管理员仅可管理所属空间内的用户权限、页面可见性及模型可用性；
|
||||
- 普通用户仅能使用被显式授权的模型与功能，其 API Key 行为严格继承归属空间的模型权限。
|
||||
> **注意**：文档中多次强调“默认业务空间无法设置模型调用/调优/部署限制”，但未明确说明该限制是否适用于所有地域。实际操作中，请以 [权限管理](../../raw/application-user-guide/application-permission-management/application-permission-management-overview.md) 中北京、新加坡、弗吉尼亚三地全局管理菜单的实际能力为准。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 说明 | 来源 |
|
||||
|------|------|------|
|
||||
| `workspace_id` | 业务空间唯一标识符，用于 API 请求中的 `X-Workspace-ID` Header 或请求体；获取方式见 [获取Workspace ID](https://help.aliyun.com/zh/model-studio/obtain-the-app-id-and-workspace-id) | — |
|
||||
| `qpm_limit` / `token_limit` | 模型级限流阈值，由超级管理员在全局管理菜单中为业务空间配置；单位分别为 QPM 和 tokens/minute | — |
|
||||
| `api_key` | 绑定至单一业务空间与用户的认证凭证；其可调用模型范围、限流值完全继承所属业务空间的模型权限配置 | — |
|
||||
| `role_policy` | RAM 策略名，如 `AliyunBailianFullAccess`（超级管理员）、`AliyunBailianDataFullAccess`（OpenAPI 数据权限）等，需通过 RAM 控制台显式附加 | — |
|
||||
| 参数 | 说明 | 来源约束 |
|
||||
|------|------|----------|
|
||||
| `workspace_id` | 业务空间唯一标识，调用 API 时必需，可通过控制台 URL 或 [获取Workspace ID](https://help.aliyun.com/zh/model-studio/obtain-the-app-id-and-workspace-id#d3eb3cd37b7fu) 获取 | 必填，且必须与 API Key 所属空间一致 |
|
||||
| `qpm_limit` / `token_limit` | 模型级每分钟请求数与 [Token](../concepts/token.md) 消耗上限，由超级管理员在业务空间模型管理页设置 | 仅对非默认业务空间生效，[权限管理](../../raw/application-user-guide/application-permission-management/application-permission-management-overview.md) 明确指出默认空间不支持限流 |
|
||||
| `api_key` | 绑定至单一地域、单一业务空间、单一用户的密钥，其可调用模型范围与限流策略完全继承自归属空间 | 不可迁移，不可复用；华北2（北京）新创建 API Key 默认归属主账号 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **角色初始化**
|
||||
- 超级管理员：主账号或已附加 `AliyunBailianFullAccess` 策略的 RAM 用户，通过 [全局管理菜单](https://bailian.console.aliyun.com/?tab=globalset#/efm/business_management) 管理所有空间。
|
||||
- 业务空间管理员：由超级管理员或同空间管理员在控制台 **权限管理 → 用户管理** 中授予“管理员”角色。
|
||||
1. **角色初始化**：
|
||||
- 超级管理员需在 RAM 控制台为 RAM 用户附加 `AliyunBailianFullAccess` 策略；
|
||||
- 业务空间管理员由超级管理员或同级管理员在控制台 **权限管理 → 用户管理** 中授予“管理员”角色。
|
||||
|
||||
2. **模型权限开通（必需前置步骤）**
|
||||
超级管理员需先在全局管理中为指定业务空间启用目标模型的“调用”“调优”或“部署”开关；未开通则下游用户即使有操作权限也无法生效。
|
||||
2. **模型权限开通**：
|
||||
- 超级管理员进入全局管理菜单（如 [北京](https://bailian.console.aliyun.com/?tab=globalset#/efm/business_management)），为指定业务空间启用目标模型的“调用”“调优”或“部署”开关；
|
||||
- 业务空间管理员在本空间内为用户分配对应控制台权限（如“模型体验-操作”“模型调优-操作”等），详见 [权限管理](../../raw/application-user-guide/application-permission-management/application-permission-management-overview.md) 中“常用设置”章节。
|
||||
|
||||
3. **控制台权限分配**
|
||||
在业务空间内进入 **权限管理 → 用户管理 → 编辑用户权限**，勾选对应功能模块（如“模型体验-操作”“模型调优-操作”等）。
|
||||
|
||||
4. **API Key 分配与使用**
|
||||
- 业务空间管理员可在 **权限管理 → API Key 管理** 中为用户创建 Key；
|
||||
- 调用时需在请求 Header 中携带 `Authorization: Bearer <api_key>` 及 `X-Workspace-ID: <workspace_id>`；
|
||||
- Key 的模型访问范围与限流策略**完全由其归属业务空间决定**，与用户账号的控制台权限无关。
|
||||
3. **API 调用授权**：
|
||||
- 为用户生成归属该业务空间的 API Key；
|
||||
- 若需调用应用类 OpenAPI（如知识库、[Prompt 工程](../concepts/prompt-engineering.md)），主账号须额外在 RAM 控制台授予 `AliyunBailianDataFullAccess` 或 `AliyunBailianDataReadOnlyAccess` 策略——**RAM 用户默认无此权限**。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域隔离性**：业务空间严格绑定单一地域（如 `cn-beijing`），跨地域资源不可共享；同一业务空间名称在不同地域视为独立实体。
|
||||
- **默认空间不可配置**：所有限流与模型开关功能仅对**非默认业务空间**生效；生产环境务必新建独立空间 [原文标题](../../raw/application-user-guide/application-permission-management/application-permission-management-overview.md)。
|
||||
- **OpenAPI 权限独立**：RAM 用户默认无权调用应用、知识库、[Prompt 工程](../concepts/prompt-engineering.md)等 OpenAPI；必须由主账号在 RAM 控制台额外授予 `AliyunBailianDataFullAccess` 或 `AliyunBailianDataReadOnlyAccess` 策略。
|
||||
- **API Key 生命周期**：当 RAM 用户被移出业务空间时，其 API Key **临时失效**（重新加入后恢复）；若在 RAM 控制台彻底删除该用户，则 Key **永久失效且不可恢复**。
|
||||
- **账单与预付费权限分离**：查看账单需 `AliyunBSSReadOnlyAccess`，购买预付费产品需 `AliyunBSSOrderAccess`；二者均需主账号在 RAM 控制台显式授权，不随百炼角色自动继承。
|
||||
- **地域隔离刚性**：业务空间与地域强绑定，同一业务空间名称在不同地域视为完全独立实体，权限不互通。
|
||||
- **默认空间能力缺失**：默认业务空间不支持模型调用/调优/部署的开关控制，也不支持任何限流配置，生产环境务必使用新建业务空间。
|
||||
- **API Key 绑定不可变**：一个 API Key 仅归属一个地域、一个业务空间、一个用户，删除用户或将其移出空间将导致 API Key 失效（重新加入可恢复）。
|
||||
- **OpenAPI 权限独立授权**：控制台页面权限与 OpenAPI 调用权限分离，即使用户拥有完整控制台权限，若未被授予 `AliyunBailianData*Access` 策略，仍无法调用应用相关 OpenAPI。
|
||||
- **账单与预付费权限需单独配置**：RAM 用户查看账单需 `AliyunBSSReadOnlyAccess`，购买预付费产品需 `AliyunBSSOrderAccess`，二者均需主账号在 RAM 控制台显式授予。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,45 +1,50 @@
|
||||
# application publishing and sharing
|
||||
|
||||
百炼平台支持将已发布的智能体应用（Agent 1.0）或工作流应用以多种方式对外共享与集成，包括 UI 应用、钉钉/微信机器人、可复用组件及音视频实时互动等渠道。所有发布行为均需基于已成功发布的应用，并受 Agent 版本、权限空间和计费模型约束。开发者应根据目标场景选择合适发布方式，并注意参数配置与调用限制。
|
||||
百炼平台支持将已发布的智能体应用（Agent 1.0）或工作流应用以多种方式对外发布与共享，包括 UI 应用、钉钉/微信机器人、可复用组件及音视频实时互动渠道。所有发布行为均需基于已发布的应用，并受 Agent 版本、业务空间隔离和权限模型约束。发布后的调用费用由应用创建者 UID 承担。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **仅限 Agent 1.0**：魔笔分享渠道、钉钉、微信、组件发布、音视频实时互动等功能**均不支持 Agent 2.0** 应用，后者仅可通过 API 调用接入 [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md)。
|
||||
- **UI 应用**：支持智能体应用与工作流应用作为后端能力，通过魔笔低代码平台构建网页界面，支持 PC/H5 多端访问 [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)。
|
||||
- **组件化能力**：智能体或工作流应用可发布为可复用组件，供其他智能体（作为工具）或工作流（作为节点）引用，实现功能解耦与复用 [使用智能体或工作流作为组件](../../raw/application-user-guide/application-publishing-and-sharing/use-agent-or-workflow-as-component.md)。
|
||||
- **音视频实时互动**：仅支持图文对话类应用（含智能体与工作流），提供 H5/APP 扫码体验及 SDK 集成两种发布路径。
|
||||
- **仅限 Agent 1.0**：魔笔 UI 应用、钉钉机器人、微信公众号、组件化发布、音视频实时互动等功能**全部仅支持 Agent 1.0 智能体应用**；Agent 2.0 应用不支持上述任何分享渠道，仅可通过 API 调用 [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md)。
|
||||
- **UI 应用**：依托魔笔低代码能力，支持拖拽式界面构建，集成智能体/工作流、数据库、HTTP 服务等资源，可发布至开发环境（免费、24 小时有效期）或生产环境（需订阅套餐）[UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)。
|
||||
- **组件化能力**：智能体或工作流应用均可发布为组件，供其他智能体（作为工具自动调用）或工作流（作为节点手动接入）复用；组件支持预设系统参数 `query` 和 `imageList`，并可配置别名、可见性、传参方式等 [使用智能体或工作流作为组件](../../raw/application-user-guide/application-publishing-and-sharing/use-agent-or-workflow-as-component.md)。
|
||||
- **音视频实时互动**：仅支持图文类应用（含智能体和工作流），提供 H5/APP 扫码体验与 SDK 集成两种发布路径，依赖 AICallKit SDK。
|
||||
|
||||
> **注意**：文档 1 明确指出“Agent 2.0 仅支持通过 API 调用”，而文档 2 和文档 3 均未提及 Agent 2.0 对组件或 UI 的支持能力，因此当前所有发布渠道均严格限定于 Agent 1.0 应用，该限制具有一致性，无矛盾。
|
||||
> **注意**：文档 1 中称“音视频实时互动仅支持百炼的图文对话类应用（含智能体应用和工作流应用）”，而文档 3 的 UI 设计器部分未提及音视频能力，且其核心定位是 Web UI 发布——二者功能边界明确，无矛盾；但需注意音视频互动与 UI 应用属不同发布通道，不可混用。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数类别 | 参数名 | 说明 | 来源依据 |
|
||||
|----------|--------|------|----------|
|
||||
| **通用认证** | API Key | 所有发布渠道（钉钉、微信、音视频、UI）均需绑定同一业务空间下的有效 API Key；未匹配时无法完成授权或配置 [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md) |
|
||||
| **组件参数** | `query`（预设） | 系统级必填 String 参数，用于传递用户文本输入；不可删除，但可设为“不可见” [使用智能体或工作流作为组件](../../raw/application-user-guide/application-publishing-and-sharing/use-agent-or-workflow-as-component.md) |
|
||||
| **组件参数** | `imageList`（预设） | Array<String> 类型，用于传递图像公网地址；仅当组件使用视觉模型时生效，否则建议设为“不可见” [使用智能体或工作流作为组件](../../raw/application-user-guide/application-publishing-and-sharing/use-agent-or-workflow-as-component.md) |
|
||||
| **组件传参** | `biz_param` | API 调用时显式传入业务参数的字段名，用于填充“业务透传”类参数 [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md) |
|
||||
| 参数 | 说明 | 约束 |
|
||||
|------|------|------|
|
||||
| `API Key` | 所有发布渠道（钉钉、微信、音视频、UI）均需绑定同一业务空间下的有效 API Key。若不可选，请检查业务空间一致性 [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)。 | 必填；跨业务空间无效 |
|
||||
| `query` / `imageList` | 组件预设系统参数：`query`（String，必填）用于传递用户文本输入；`imageList`（Array<String>，非必填）用于图像理解场景。不可删除，但可通过“是否可见”控制暴露 [使用智能体或工作流作为组件](../../raw/application-user-guide/application-publishing-and-sharing/use-agent-or-workflow-as-component.md)。 | 仅组件场景生效 |
|
||||
| `传参方式` | 分 `业务透传`（调用方显式传入）与 `模型识别`（仅智能体中由大模型自动填充）；**工作流中无论设置为何，均需上游节点显式传值** [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md)。 | 工作流不支持模型识别自动填充 |
|
||||
| `回调地址` / `二维码` / `分享链接` | 钉钉/微信发布后生成的唯一访问入口；UI 应用和音视频互动提供临时二维码（24 小时）或长期链接；生产环境 UI 需绑定自定义域名 [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)。 | 时效性差异显著，生产部署需规划 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **入口统一**：所有发布操作均从百炼控制台 **[应用管理](https://bailian.console.aliyun.com/?tab=app#/app-center)** 页面进入，点击目标应用卡片的 **发布** 按钮。
|
||||
2. **渠道选择**：
|
||||
- **UI 应用**：在“发布渠道”页签选择“UI 应用” → 创建 → 编辑界面 → 发布至开发/生产环境；开发环境链接有效期为 24 小时 [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)。
|
||||
- **钉钉/微信**：在“发布平台”页签分别点击对应卡片的“创建”，完成第三方平台授权（需 SLR 角色与 API Key）、凭证配置（Client ID/Secret、模板 ID、AppID）及回调地址/二维码分发 [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md)。
|
||||
- **组件**：在“发布渠道”页签点击“组件” → “+ 创建”，填写名称、描述、参数别名/可见性/传参方式（业务透传 或 模型识别）→ 发布；后续可在智能体“技能”或工作流画布中拖入引用 [使用智能体或工作流作为组件](../../raw/application-user-guide/application-publishing-and-sharing/use-agent-or-workflow-as-component.md)。
|
||||
- **音视频实时互动**：在“AI 实时互动”页签配置 API Key → 生成临时二维码测试 → 发布后开通智能媒体服务并完成 SLR 授权 → 选择 H5/APP 分享或 SDK 集成 [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md)。
|
||||
1. **前置条件**：确保目标应用已**发布成功**，且与 API Key、UI 设计器、钉钉/微信配置处于**同一业务空间** [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)。
|
||||
2. **统一入口**：进入百炼控制台 → **应用管理** → 打开目标应用 → 切换至对应页签：
|
||||
- `发布` 或 `发布渠道`：操作魔笔 UI、钉钉、微信、组件；
|
||||
- `AI实时互动`：配置音视频；
|
||||
- `UI设计器`：独立入口（`#/app-ui`）用于从零构建或导入已有应用。
|
||||
3. **组件发布流程**：
|
||||
- 方式一：发布应用时勾选“发布应用组件”；
|
||||
- 方式二：在 `组件管理` 页面（`#/component-manage`）或应用发布渠道页签点击 `+ 创建`；
|
||||
- 配置名称、描述、参数（别名、是否可见、传参方式、默认值）后确认 [使用智能体或工作流作为组件](../../raw/application-user-guide/application-publishing-and-sharing/use-agent-or-workflow-as-component.md)。
|
||||
4. **UI 应用发布**：
|
||||
- 从应用发布渠道选择 `UI应用` → 自动填充基础信息（API Key、智能体等）→ 编辑 → 发布；
|
||||
- 或直接进入 UI 设计器 → 选模板 → 配置 → 拖拽编辑 → 发布至开发/生产环境 [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **Agent 版本硬约束**：Agent 2.0 应用**完全不可用于任何 UI、钉钉、微信、组件或音视频发布渠道**，仅支持 API 调用，此为平台级限制 [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md)。
|
||||
- **业务空间一致性**：UI 设计器、API Key、目标应用必须归属同一业务空间，否则无法在 UI 创建流程中选择对应资源 [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)。
|
||||
- **组件调用风险**：
|
||||
- **禁止嵌套调用**（A→B→A）：将导致无限循环，应用不可用；
|
||||
- **慎用多级调用**（A→B→C）：受最长运行时间限制，易超时失败 [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md)。
|
||||
- **环境与计费**：
|
||||
- UI 开发环境免费但链接 24 小时失效；生产环境需订阅付费套餐并绑定自定义域名 [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)；
|
||||
- 所有通过分享链接产生的模型调用费用，均由应用创建者 UID 账号承担 [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md)。
|
||||
- **工作流中“模型识别”无效**：即使组件参数设为“模型识别”，在工作流中仍需上游节点显式传入值，大模型不会自动推断 [使用智能体或工作流作为组件](../../raw/application-user-guide/application-publishing-and-sharing/use-agent-or-workflow-as-component.md)。
|
||||
- **Agent 版本硬限制**：Agent 2.0 应用**完全不支持**魔笔、钉钉、微信、组件、音视频等所有分享渠道，仅开放 API 接口 [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md)。
|
||||
- **嵌套与多级调用风险**：组件间禁止 A→B→A 循环调用（导致死循环）；A→B→C 多级调用易触发超时，建议扁平化设计 [分享智能体应用](../../raw/application-user-guide/application-publishing-and-sharing/share-an-application.md)。
|
||||
- **工作流中组件参数约束**：即使配置为 `模型识别`，工作流也**不会自动推断参数值**，必须由上游节点显式传入 [使用智能体或工作流作为组件](../../raw/application-user-guide/application-publishing-and-sharing/use-agent-or-workflow-as-component.md)。
|
||||
- **环境与计费差异**：
|
||||
- UI 开发环境链接 24 小时失效，生产环境需订阅付费套餐并配置域名；
|
||||
- 所有分享渠道产生的模型调用费用均由应用创建者 UID 承担；
|
||||
- 文件存储与数据库超出免费配额（1GB 文件 / 0.3GB DB）后按量计费 [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)。
|
||||
- **权限与访问控制**：默认仅阿里云用户可访问分享链接；如需匿名访问，须在 UI 设计器中启用“允许匿名访问”并配置权限组 [UI设计器](../../raw/application-user-guide/application-publishing-and-sharing/ui-designer.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,45 +1,42 @@
|
||||
# application support
|
||||
|
||||
`application support` 指百炼平台为开发者在构建和运行 AI 应用（如智能体、RAG 应用、[插件](../concepts/plugin.md)集成等）过程中提供的功能能力、调用接口、参数配置及配套支持服务。它涵盖模型与[插件](../concepts/plugin.md)能力接入、流式/增量输出控制、知识检索增强（RAG）机制、API 调用限制与售后响应边界等核心环节，是应用稳定上线与持续迭代的技术基础。开发者需结合具体场景选择合适的能力组合，并严格遵循平台约束条件。
|
||||
`application support` 指百炼平台为开发者在构建和运行 AI 应用（如智能体、RAG 应用、插件集成等）过程中提供的功能支持、接口能力、参数配置及配套服务保障。它覆盖模型调用、插件扩展、知识库检索、[流式输出](../concepts/streaming-output.md)等核心开发环节，并包含明确的服务边界与售后支持范围。开发者需结合具体场景选择合适的能力组合，并注意平台限制与协议约束。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **内置[插件](../concepts/plugin.md)能力**：当前官方支持六类插件：Python 代码解释器、计算器、图片生成、夸克搜索、生成二维码、GitHub 搜索。部分插件需申请开通 [常见问题 (raw/application-user-guide/application-support/application-faq.md)](../../raw/application-user-guide/application-support/application-faq.md)。
|
||||
- **RAG（知识检索增强）**：支持多知识库并行检索，按用户配置的权重与相似度得分选取 topN 片段后融合生成，广泛应用于问答系统、客户服务、教育培训等场景 [常见问题 (raw/application-user-guide/application-support/application-faq.md)](../../raw/application-user-guide/application-support/application-faq.md)。
|
||||
- **自定义插件**：支持通过符合协议的 API 接入，大模型可理解其参数结构并自主调用；但**不支持透传自定义 Header**，仅允许 `Authorization` 字段 [常见问题 (raw/application-user-guide/application-support/application-faq.md)](../../raw/application-user-guide/application-support/application-faq.md)。
|
||||
- **流式与增量输出**：可通过 `stream=True` 启用流式响应；进一步设置 `incremental_output=True` 实现真正增量式 token 输出（即每次返回新生成内容，而非全量重发）。
|
||||
- **内置插件能力**：当前官方支持六类插件，包括 Python 代码解释器、计算器、图片生成、夸克搜索、生成二维码、GitHub 搜索；部分插件需申请开通 [常见问题](../../raw/application-user-guide/application-support/application-faq.md)。
|
||||
- **RAG（知识检索增强）**：支持多知识库并行检索，按配置得分选取 topN 结果后融合生成，适用于问答系统、客服、教育等场景 [常见问题](../../raw/application-user-guide/application-support/application-faq.md)。
|
||||
- **自定义插件/API 函数**：支持通过协议声明函数签名，大模型可理解参数结构并生成调用请求；但**不支持透传自定义 Header**，仅允许 `Authorization` 字段 [常见问题](../../raw/application-user-guide/application-support/application-faq.md)。
|
||||
- **流式与增量输出**：可通过 `stream=True` 启用流式响应；进一步设置 `incremental_output=True` 实现增量式[流式输出](../concepts/streaming-output.md)（即每次返回新 token 而非全量重发）。
|
||||
|
||||
> **注意**：文档 1 中“Agent 和 Assistant API 的最大区别”描述模糊且缺乏技术细节（如未说明 Agent 是否指百炼原生智能体或第三方框架），该条目未被其他文档佐证，建议以控制台实际能力与 [阿里云百炼平台售后服务范围说明 (raw/application-user-guide/application-support/application-after-sales-service-scope.md)](../../raw/application-user-guide/application-support/application-after-sales-service-scope.md) 中定义的服务边界为准。
|
||||
> **注意**：文档中提及“Agent 和 Assistant API 的最大区别是调整插件模型、基于上下文的理解，用户可以自己去开发”，该描述模糊且未定义关键术语（如“调整插件模型”具体指代何种操作），与当前百炼控制台实际能力不符；建议以[阿里云百炼平台售后服务范围说明](../../raw/application-user-guide/application-support/application-after-sales-service-scope.md)中明确的服务边界为准，避免对能力边界产生误判。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 类型 | 说明 | 示例 |
|
||||
|------|------|------|------|
|
||||
| `stream` | bool | 控制是否启用流式响应 | `True` |
|
||||
| `incremental_output` | bool | 在 `stream=True` 基础上启用增量式输出（避免重复渲染） | `True` |
|
||||
| `top_k`（RAG） | int | 检索结果返回的最大片段数 | `3` |
|
||||
| `score_threshold`（RAG） | float | 过滤低相关性检索结果的阈值 | `0.3` |
|
||||
| `MD5`（文件上传） | string | 用于校验上传文件完整性，必填 | `"d41d8cd98f00b204e9800998ecf8427e"` |
|
||||
| 参数名 | 类型 | 说明 | 示例 |
|
||||
|--------|------|------|------|
|
||||
| `stream` | bool | 启用[流式输出](../concepts/streaming-output.md) | `True` |
|
||||
| `incremental_output` | bool | 启用增量式流式输出（需配合 `stream=True`） | `True` |
|
||||
| `MD5` | string | 文件上传必填，用于校验文件完整性 | `"d41d8cd98f00b204e9800998ecf8427e"` |
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **插件调用**：在智能体配置中启用对应插件，自定义插件需提供符合 OpenAPI 3.0 规范的 Schema 描述；模型将基于 Schema 自动解析参数并构造请求。
|
||||
- **RAG 配置**：在应用编辑页绑定知识库，设置检索策略（如关键词+向量混合）、重排序规则及上下文长度限制。
|
||||
- **流式/增量输出**：在调用 `Assistant API` 或 `ChatCompletion` 接口时，显式传入 `stream=True` 和 `incremental_output=True`。前端需按 chunk 解析并拼接，而非累积覆盖。
|
||||
- **文件上传**：仅支持 `.pdf`（小写后缀）、`.doc`、`.docx`；结构化数据导入需确保无空行，否则后续行将被忽略。
|
||||
- 插件调用：在智能体配置中启用对应插件，自定义插件需按 OpenAPI Schema 规范定义函数描述；调用时由大模型自动解析参数并构造请求。
|
||||
- RAG 应用：上传 PDF/DOC/DOCX 格式知识文档（注意 PDF 后缀必须为小写 `pdf`），单业务空间上限 10 万文档，超限时需提交工单申请扩容 [常见问题](../../raw/application-user-guide/application-support/application-faq.md)。
|
||||
- 错误排查：RAG 输出不准确时，可通过回复下方“问题反馈”按钮提交，或复制 `RequestId` 提交工单 [常见问题](../../raw/application-user-guide/application-support/application-faq.md)。
|
||||
- 渲染处理：模型输出含 `**text**` 等 Markdown 语法时，需在前端自行解析渲染，平台不提供富文本转换能力。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **插件限制**：自定义插件不支持除 `Authorization` 外的任何 HTTP Header 透传；非官方插件的稳定性、安全性及计费归属由用户自行承担。
|
||||
- **知识库容量**：单业务空间最多支持 10 万个文档，超限时需提交工单申请扩容 [常见问题 (raw/application-user-guide/application-support/application-faq.md)](../../raw/application-user-guide/application-support/application-faq.md)。
|
||||
- **售后支持边界**：阿里云百炼仅保障自身服务端（API、控制台、计费系统）的可用性与正确性；**不支持**第三方工具（如 Cursor、Windsurf 等）的部署、配置、调试，也不承担其与百炼集成过程中的兼容性问题 [阿里云百炼平台售后服务范围说明 (raw/application-user-guide/application-support/application-after-sales-service-scope.md)](../../raw/application-user-guide/application-support/application-after-sales-service-scope.md)。
|
||||
- **合规要求**：接入通义千问模型的应用上架至应用市场或小程序平台前，必须完成[应用合规备案](https://help.aliyun.com/zh/model-studio/compliance-and-launch-filing-guide-for-ai-apps-powered-by-the-tongyi-model)，并签署合作协议。
|
||||
- **协议约束**：所有使用均须遵守《[阿里云百炼服务协议](https://terms.alicdn.com/legal-agreement/terms/common_platform_service/20230728213935489/20230728213935489.html?spm=5176.28197581.0.0.16e829a4HTC9FE)》及《[阿里云百炼体验功能特别说明](https://terms.alicdn.com/legal-agreement/terms/common_platform_service/20260716114753386/20260716114753386.html)》 [相关协议 (raw/application-user-guide/application-support/application-related-agreements.md)](../../raw/application-user-guide/application-support/application-related-agreements.md)。
|
||||
- **Header 限制**：自定义插件调用时，仅支持透传 `Authorization` 请求头，其他 Header（如 `X-User-ID`、`Cookie`）将被丢弃。
|
||||
- **文件格式与结构**：上传文件仅支持 `.pdf`（小写）、`.doc`、`.docx`；结构化数据导入时，空行会导致后续行被跳过，首行为空则视为无效文件 [常见问题](../../raw/application-user-guide/application-support/application-faq.md)。
|
||||
- **第三方工具支持边界**：阿里云百炼仅保障自身服务端（API、SDK、控制台、计费系统）的可用性与正确性；对 Cursor、Windsurf 等第三方工具的安装、配置、本地环境（代理/防火墙/OS）或业务代码问题，不提供直接支持，仅提供方向性建议 [阿里云百炼平台售后服务范围说明](../../raw/application-user-guide/application-support/application-after-sales-service-scope.md)。
|
||||
- **协议约束**：使用前须遵守《阿里云百炼服务协议》《体验功能特别说明》及开源模型相关条款，详见 [相关协议](../../raw/application-user-guide/application-support/application-related-agreements.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [常见问题](../../raw/application-user-guide/application-support/application-faq.md)
|
||||
- [阿里云百炼平台售后服务范围说明](../../raw/application-user-guide/application-support/application-after-sales-service-scope.md)
|
||||
- [相关协议](../../raw/application-user-guide/application-support/application-related-agreements.md)
|
||||
- [阿里云百炼平台售后服务范围说明](../../raw/application-user-guide/application-support/application-after-sales-service-scope.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,53 +1,55 @@
|
||||
# application [use cases](use-cases.md)
|
||||
|
||||
百炼平台支持多种主流业务场景下的 AI 应用快速落地，涵盖网站嵌入、企业微信、钉钉、微信公众号等私域渠道的智能客服/助手集成，以及本地化知识库驱动的 RAG 应用。所有方案均基于百炼大模型 API 与 AppFlow 低代码连接能力构建，无需自建推理服务或编写复杂集成逻辑，开发者可聚焦于业务逻辑与效果调优。
|
||||
百炼平台支持多种主流企业通讯与网站渠道的 AI 助手快速集成，核心模式为“大模型应用 + RAG 知识增强 + 低代码连接流”。所有方案均基于统一的百炼大模型应用作为推理后端，通过 AppFlow 实现与外部渠道（如网站、企业微信、微信公众号、钉钉）的零编码对接，并支持私有知识库注入以提升领域回答准确性。开发者可复用同一套模型配置和知识库，灵活部署至不同触点。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **核心模型**：统一支持通义千问系列商用模型，包括 `qwen-max`（高精度）、`qwen-plus`（均衡型，[原文标题](../../raw/application-user-guide/application-use-cases/add-an-ai-assistant-to-your-website-in-10-minutes.md) 中明确推荐用于网站助手场景）、`qwen-turbo`（低延迟）及 `qwen3.5-plus`（文档 1 中指定为最新推荐版本）。
|
||||
- **RAG 能力**：所有集成方案均默认支持知识库增强，通过百炼控制台的「知识库」模块接入结构化/非结构化文档（PDF、DOCX、TXT、XLSX 等），支持向量检索与全文引用两种模式。
|
||||
- **多端交互能力**：提供开箱即用的 Web 悬浮挂件、企业微信应用、钉钉机器人、微信公众号智能客服四类标准化集成形态，均支持自定义 Prompt、图标、预置问题及对话样式。
|
||||
- **本地 RAG 扩展**：除云端知识库外，[原文标题](../../raw/application-user-guide/application-use-cases/build-rag-application-based-on-local-retrieval.md) 提供基于本地文件系统 + 百炼 Embedding API 的轻量级 RAG 方案，适用于对数据驻留有强要求的场景。
|
||||
- **基础模型**：推荐使用 `Qwen3.5-Plus`（文档 1 明确指定）或 `千问-Plus`（文档 2、3、4 均采用），该模型在效果、速度与成本间取得平衡，适用于通用客服问答场景。`qwen-turbo` 可用于对响应延迟敏感的场景（如未认证公众号的 5 秒限制），但需权衡生成质量 [原文标题](../../raw/application-user-guide/application-use-cases/build-rag-application-based-on-local-retrieval.md)。
|
||||
- **RAG 能力**：所有集成方案均依赖百炼知识库实现私域知识增强，支持 PDF、DOCX、TXT、XLSX 等格式（文档 2、3、4、5 均明确列出），最大单文件 100 MB（文档 2、5 提及）。
|
||||
- **扩展能力**：支持对话日志记录至 SLS（文档 2、3、4 均提供详细步骤）、卡片消息渲染（文档 4）、DeepSeek 思考过程展示（文档 4）等高级功能。
|
||||
|
||||
> **注意**：文档 1 明确指定模型为 `Qwen3.5-Plus`，而文档 2–4 均使用 `千问-Plus`（即 `qwen-plus`）。二者为同一模型的不同命名表述，实际调用时应以百炼控制台当前可用模型列表为准；若控制台未显示 `Qwen3.5-Plus`，请选用 `qwen-plus`。
|
||||
> **注意**：文档 1 指定模型为 `Qwen3.5-Plus`，而文档 2、3、4 统一使用 `千问-Plus`。当前控制台中 `Qwen3.5-Plus` 是 `千问-Plus` 的演进版本，二者 API 兼容，但 `Qwen3.5-Plus` 在中文理解与指令遵循上略有提升。建议新项目优先选用 `Qwen3.5-Plus`，存量项目无需强制迁移。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数类别 | 参数名 | 说明 | 可配置位置 |
|
||||
|----------|--------|------|------------|
|
||||
| **模型层** | `temperature` | 控制生成随机性，范围 0–2，推荐值 0.3–0.7 | [原文标题](../../raw/application-user-guide/application-use-cases/build-rag-application-based-on-local-retrieval.md) 的「优化回复效果」章节 |
|
||||
| | `max_tokens` | 最大输出长度，影响响应详略程度 | 同上 |
|
||||
| | `top_p` / `top_k` | 核采样参数，控制候选 token 范围 | 百炼应用配置页「高级设置」 |
|
||||
| **RAG 层** | `retrieval_top_k` | 召回片段数，默认 3–5 | 百炼应用配置页「知识库」→「调用方式」旁设置项；本地 RAG 方案见 [原文标题](../../raw/application-user-guide/application-use-cases/build-rag-application-based-on-local-retrieval.md) |
|
||||
| | `similarity_threshold` | 相似度阈值，过滤低相关片段，默认 0.3–0.6 | 同上 |
|
||||
| | `chunk_size` / `chunk_overlap` | 文档切分粒度（仅本地 RAG 可调） | [原文标题](../../raw/application-user-guide/application-use-cases/build-rag-application-based-on-local-retrieval.md) 的「优化切分方法」章节 |
|
||||
- **身份凭证**：所有方案均需百炼 `App ID` 与 `API Key`（文档 1、2、3、4 均要求），用于 AppFlow 调用模型服务；各渠道还需对应平台凭证（如企业微信的 `CorpID/AgentID/Secret`、钉钉的 `Client ID/Client Secret`、微信公众号的 `AppID`）。
|
||||
- **知识库配置**：
|
||||
- 调用方式：推荐设为 `必定调用`（文档 1、2、3、4 均采用），确保知识检索始终生效；
|
||||
- 向量存储：可选 `ADB-PG` 以集中管理多应用向量数据（文档 1、2、3、4 均提及）；
|
||||
- 文档处理：支持 `全文引用`、`切片检索`、`自定义处理`（文档 2 明确列出）。
|
||||
- **RAG 参数（本地部署场景）**：文档 5 提供细粒度控制，包括召回片段数、相似度阈值、温度、最大回复长度等，适用于需深度调优的定制化部署 [原文标题](../../raw/application-user-guide/application-use-cases/build-rag-application-based-on-local-retrieval.md)。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **创建百炼应用**：在百炼控制台「应用管理」中创建「智能体应用」，选择目标模型（如 `qwen-plus`），配置 Prompt（例如 `"你叫小助，帮助解答产品选购、使用问题"`），发布应用并记录 `AppID` 与 `API Key`。
|
||||
2. **配置知识库（可选但推荐）**：
|
||||
- 上传文档至「数据连接」或「文件」页签；
|
||||
- 在「知识库」页签创建标准版知识库，关联上传文件；
|
||||
- 在应用配置中启用知识库，设置调用方式为「必定调用」。
|
||||
3. **集成到目标平台**：
|
||||
- **网站**：通过 AppFlow 创建「AI助手」→ 配置百炼凭证 → 获取悬浮挂件脚本 → 插入 HTML。
|
||||
- **企业微信/钉钉/微信公众号**：在对应平台创建应用获取凭证（AgentId/Secret 或 ClientID/ClientSecret 或 AppID），再通过 AppFlow 预置模板（如「企业微信自建应用大模型自动回复」）一键绑定百炼应用与 Webhook。
|
||||
4. **验证与调优**：在目标渠道发起测试对话，结合人工评测结果调整 Prompt、知识库覆盖范围或 RAG 参数。
|
||||
1. **创建百炼应用**：在百炼控制台选择“智能体应用”，配置 Prompt（如 `你叫小助，可以帮助用户解答产品选购、使用等方面的问题`），并发布应用（文档 1、2、3、4 均含此步骤）。
|
||||
2. **配置知识库**：上传私有文档 → 创建知识库 → 在应用配置中绑定知识库并设为“必定调用”（文档 1、2、3、4 流程一致）。
|
||||
3. **构建连接流**：
|
||||
- 网站场景：使用 AppFlow 创建“AI助手”，导入百炼应用，生成悬浮挂件脚本嵌入 HTML（文档 1）；
|
||||
- 企业微信/钉钉/微信公众号：使用 AppFlow 预置模板（文档 2、3、4 均提供专属模板链接），完成平台凭证授权与百炼凭证绑定，获取 Webhook URL。
|
||||
4. **渠道侧配置**：
|
||||
- 网站：插入 JS 脚本（文档 1）；
|
||||
- 企业微信：配置 API 接收消息（URL=Webhook）与可信 IP（文档 2）；
|
||||
- 微信公众号：开启服务器配置，注意认证状态影响消息接口（文档 3 强调已认证/未认证两种工作流）；
|
||||
- 钉钉：配置机器人 HTTP 模式接收地址（文档 4 明确要求禁用 Stream 模式）。
|
||||
|
||||
> **注意**：文档 3 特别指出，未认证公众号受 5 秒响应限制，若百炼应用超时将导致回复失败，此时需优化 Prompt（如添加“请总是给出简短的回答”）或切换至 `qwen-turbo` 模型 [原文标题](../../raw/application-user-guide/application-use-cases/add-an-ai-assistant-to-your-wechat-in-10-minutes.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **免费额度限制**：新用户享有百炼免费额度，覆盖教程全部资源消耗；超出后按 token 计费，详见 [原文标题](../../raw/application-user-guide/application-use-cases/add-an-ai-assistant-to-your-website-in-10-minutes.md) 中的额度说明。
|
||||
- **微信公众号认证约束**：未认证公众号仅支持被动回复（5 秒超时限制），已认证方可启用客户消息接口；若未认证且需稳定响应，建议切换至 `qwen-turbo` 模型或优化 Prompt 缩短响应时间。
|
||||
- **知识库文件限制**：单文档最大 100 MB 或 1000 页，图片单张最大 20 MB，总文件数上限 200 个（文档 2 明确说明）；本地 RAG 方案同样不建议上传 >100 MB 文件（文档 5 提示）。
|
||||
- **可信 IP 与域名校验**：企业微信/钉钉等平台要求配置可信 IP 和主体备案域名。当 AppFlow 自动生成的 Webhook 域名校验失败时，需按文档 2 的「常见问题」章节配置二级域名或 Nginx 代理。
|
||||
- **模型兼容性**：钉钉机器人必须使用 HTTP 模式接收消息（文档 3 强调），Stream 模式将导致消息无法返回；企业微信需严格配置 [Token](../concepts/token.md) 和 EncodingAESKey（文档 2 的 4.1 节）。
|
||||
- **免费额度**：新用户可使用百炼免费额度覆盖全部教程资源消耗，额度用尽后按 token 计费（文档 1、2、4 均强调）。
|
||||
- **文件解析时效**：上传文档后需等待 1–6 分钟完成解析（文档 1、2、3、4 均提示），期间知识库不可用。
|
||||
- **渠道限制**：
|
||||
- 微信公众号未认证时仅支持被动回复，且响应必须 ≤5 秒（文档 3）；
|
||||
- 钉钉机器人必须使用 HTTP 模式，Stream 模式不兼容（文档 4）；
|
||||
- 企业微信配置需解决域名主体校验与可信 IP 冲突问题（文档 2 提供 Nginx 代理等完整解决方案）。
|
||||
- **本地部署补充**：文档 5 提供基于 Python 的本地 RAG 方案，适用于需完全掌控文档切分、嵌入模型选择的场景，但需自行维护计算环境 [原文标题](../../raw/application-user-guide/application-use-cases/build-rag-application-based-on-local-retrieval.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [在网站上增加一个AI助手](../../raw/application-user-guide/application-use-cases/add-an-ai-assistant-to-your-website-in-10-minutes.md)
|
||||
- [在企业微信中集成一个 AI 助手](../../raw/application-user-guide/application-use-cases/add-an-ai-assistant-to-your-work-wechat.md)
|
||||
- [在钉钉上增加一个AI机器人](../../raw/application-user-guide/application-use-cases/add-an-ai-assistant-to-your-dingtalk.md)
|
||||
- [10分钟让微信公众号成为智能客服](../../raw/application-user-guide/application-use-cases/add-an-ai-assistant-to-your-wechat-in-10-minutes.md)
|
||||
- [在钉钉上增加一个AI机器人](../../raw/application-user-guide/application-use-cases/add-an-ai-assistant-to-your-dingtalk.md)
|
||||
- [基于本地知识库构建RAG应用](../../raw/application-user-guide/application-use-cases/build-rag-application-based-on-local-retrieval.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,87 +1,84 @@
|
||||
# bailian [application call](../api/application-call.md)ing
|
||||
|
||||
百炼应用调用是将阿里云百炼平台创建的智能体应用或工作流应用集成到业务系统的核心方式，支持通过 DashScope SDK 或标准 HTTP API 进行同步调用。所有调用均需有效 API Key 和应用 ID，并遵循统一的请求结构与认证机制。该能力适用于单轮问答、多轮对话及带[插件](../concepts/plugin.md)参数的复杂任务编排。
|
||||
百炼应用调用是指通过 DashScope SDK 或 HTTP API，将百炼平台创建的智能体应用（Single Agent Application）或工作流应用（Workflow Application）集成到自有业务系统中。调用过程统一使用 `/api/v1/apps/{app_id}/completion` 接口，支持单轮/多轮对话及插件参数透传，适用于各类 AI 增强型业务场景。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **应用类型**：支持两类应用调用：
|
||||
- **智能体应用（Single Agent Application）**：面向单一角色、任务导向的轻量级智能体，适用于客服问答、知识检索等场景 [调用智能体应用](../../raw/application-user-guide/bailian-application-calling/call-single-agent-application.md)；
|
||||
- **工作流应用（Workflow Application）**：支持多节点编排（如大模型节点、[插件](../concepts/plugin.md)节点、条件分支），适用于需组合工具调用、逻辑判断的复杂业务流程 [调用工作流应用](../../raw/application-user-guide/bailian-application-calling/invoke-workflow-application.md)。
|
||||
- [调用智能体应用](../../raw/application-user-guide/bailian-application-calling/call-single-agent-application.md)（即 Single Agent Application），适用于简单意图识别+大模型响应场景；
|
||||
- [调用工作流应用](../../raw/application-user-guide/bailian-application-calling/invoke-workflow-application.md)，适用于含插件、条件分支、多节点编排的复杂逻辑场景。
|
||||
- **核心能力**：
|
||||
- 单轮文本生成（`prompt` 输入 → `text` 输出）；
|
||||
- 多轮对话支持（通过 `session_id` 或显式 `messages` 数组维护上下文）；
|
||||
- 自定义[插件](../concepts/plugin.md)参数透传（`biz_params.user_defined_params`），用于向关联插件传递业务字段 [应用的自定义参数传递](../../raw/application-user-guide/bailian-application-calling/pass-through-of-application-parameters.md)；
|
||||
- 单轮文本生成（`prompt` 输入 → `output.text` 输出）；
|
||||
- 多轮对话（通过 `session_id` 或显式 `messages` 数组维护上下文）；
|
||||
- 自定义插件参数透传（通过 `biz_params.user_defined_params` 传递插件所需业务参数）；
|
||||
- 调试信息返回（`debug` 字段可启用）；
|
||||
- [Token](../concepts/token.md) 使用统计（`usage.models` 中包含 `input_tokens`/`output_tokens` 及对应 `model_id`）。
|
||||
- [Token](../concepts/token.md) 统计与模型用量（`usage.models` 中包含 `model_id`、`input_tokens`、`output_tokens`）。
|
||||
|
||||
> **注意**：文档 2 明确声明“本文档仅适用于华北2（北京）地域”，而文档 1 和 3 均未限定地域。实际调用时若在非北京地域遇到 `404` 或 `InvalidRegionId` 错误，应优先确认应用部署地域并使用对应 endpoint —— 当前生产环境默认 endpoint 为 `https://dashscope.aliyuncs.com`，其路由已自动适配地域，但部分旧版 SDK 或手动构造 URL 的场景仍可能受地域约束。
|
||||
> **注意**：文档 2 明确声明“本文档仅适用于华北2（北京）地域”，而文档 1 和文档 3 均未限定地域。实际调用时若在非北京地域遇到 404 或地域不可用错误，请确认应用部署地域并参考 [调用工作流应用](../../raw/application-user-guide/bailian-application-calling/invoke-workflow-application.md) 的地域约束说明。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| `app_id` | string | ✓ | 百炼控制台中应用卡片显示的唯一 ID，区分智能体应用与工作流应用 |
|
||||
| `prompt` | string | ✓（除 `messages` 模式外） | 用户输入的自然语言指令；若使用 `messages` 多轮模式，则此项忽略 |
|
||||
| `biz_params` | object | ✗ | 用于传递插件参数，结构为 `{ "user_defined_params": { "<plugin_code>": { "<param_key>": <value> } } }`，详见 [应用的自定义参数传递](../../raw/application-user-guide/bailian-application-calling/pass-through-of-application-parameters.md) |
|
||||
| `parameters` | object | ✗ | 预留扩展字段，当前暂未开放通用参数配置 |
|
||||
| `debug` | object | ✗ | 设为空对象 `{}` 即可启用调试模式，返回更详细的执行链路信息 |
|
||||
| `input`（HTTP） | object | ✓ | HTTP 请求体顶层字段，必须包裹 `prompt` 或 `messages` 等子字段 |
|
||||
| `app_id` | string | ✅ | 百炼控制台应用卡片上复制的 APP_ID，区分智能体应用与工作流应用 |
|
||||
| `prompt` | string | ⚠️ | 单轮调用必需；若使用 `messages` 进行多轮对话，则此项可省略 |
|
||||
| `biz_params` | object | ❌ | 用于插件参数透传，结构为 `{ "user_defined_params": { "<plugin_code>": { "<param_key>": <value> } } }`，详见 [应用的自定义参数传递](../../raw/application-user-guide/bailian-application-calling/pass-through-of-application-parameters.md) |
|
||||
| `session_id` | string | ❌ | 启用云端会话管理时传入，有效期 1 小时，最多 50 轮；与 `messages` 同时存在时优先使用 `messages` |
|
||||
| `messages` | array | ❌ | 显式维护的对话历史数组，格式同 OpenAI `messages`（`role`, `content`），推荐用于精确上下文控制 |
|
||||
| `parameters` | object | ❌ | 预留扩展字段，当前暂无公开可用参数 |
|
||||
| `debug` | object | ❌ | 设为空对象 `{}` 可启用调试模式，返回更详细的内部执行链路信息 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 1. 准备工作
|
||||
- 获取 API Key：前往 [密钥管理](https://bailian.console.aliyun.com/?tab=model#/api-key) 创建并复制；
|
||||
- 获取 `app_id`：在 [应用管理](https://bailian.console.aliyun.com/?tab=app#/app-center) 页面复制目标应用的 ID；
|
||||
- （推荐）配置环境变量：`export DASHSCOPE_API_KEY=sk-xxx`，避免代码硬编码。
|
||||
- 获取 API Key：前往 [密钥管理](https://bailian.console.aliyun.com/?tab=model#/api-key) 创建并配置为环境变量 `DASHSCOPE_API_KEY`（[推荐做法](../../raw/application-user-guide/bailian-application-calling/call-single-agent-application.md)）；
|
||||
- 获取 `app_id`：在 [应用管理](https://bailian.console.aliyun.com/?tab=app#/app-center) 页面复制目标应用 ID；
|
||||
- （SDK 方式）安装对应语言 SDK：Python 使用 `pip install -U dashscope`；Java 需引入 `dashscope-sdk-java`（建议 ≥2.12.0）；其他语言参考各文档示例。
|
||||
|
||||
### 2. SDK 调用（Python 示例）
|
||||
```python
|
||||
from dashscope import Application
|
||||
response = Application.call(
|
||||
api_key=os.getenv("DASHSCOPE_API_KEY"), # 自动读取环境变量
|
||||
app_id="YOUR_APP_ID",
|
||||
prompt="你是谁？"
|
||||
)
|
||||
if response.status_code == 200:
|
||||
print(response.output.text)
|
||||
```
|
||||
### 2. 调用示例（统一接口）
|
||||
所有方式均请求 `POST https://dashscope.aliyuncs.com/api/v1/apps/{app_id}/completion`：
|
||||
|
||||
### 3. HTTP 直接调用（curl 示例）
|
||||
```bash
|
||||
curl -X POST https://dashscope.aliyuncs.com/api/v1/apps/YOUR_APP_ID/completion \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"input": {"prompt": "你是谁？"},
|
||||
"parameters": {},
|
||||
"debug": {}
|
||||
- **SDK（Python）**
|
||||
```python
|
||||
from dashscope import Application
|
||||
response = Application.call(
|
||||
api_key=os.getenv("DASHSCOPE_API_KEY"),
|
||||
app_id="YOUR_APP_ID",
|
||||
prompt="你是谁？",
|
||||
biz_params={"user_defined_params": {"plugin_abc123": {"query_id": 42}}}
|
||||
)
|
||||
print(response.output.text)
|
||||
```
|
||||
|
||||
- **HTTP（curl）**
|
||||
```bash
|
||||
curl -X POST https://dashscope.aliyuncs.com/api/v1/apps/YOUR_APP_ID/completion \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"input": {
|
||||
"prompt": "你是谁？",
|
||||
"biz_params": {
|
||||
"user_defined_params": {
|
||||
"plugin_abc123": {"query_id": 42}
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
```
|
||||
|
||||
### 4. 多轮对话（推荐 `messages` 模式）
|
||||
```python
|
||||
# 显式维护 messages（更可控）
|
||||
messages = [
|
||||
{"role": "user", "content": "你好"},
|
||||
{"role": "assistant", "content": "你好！我是通义千问。"},
|
||||
{"role": "user", "content": "今天天气如何？"}
|
||||
]
|
||||
response = Application.call(
|
||||
app_id="YOUR_APP_ID",
|
||||
messages=messages # 此时忽略 prompt 字段
|
||||
)
|
||||
```
|
||||
### 3. 多轮对话处理
|
||||
- **推荐方式（显式 `messages`）**：客户端自行维护 `messages` 列表，每次请求携带完整历史（含最新用户输入），避免依赖服务端状态；
|
||||
- **便捷方式（`session_id`）**：首次调用后从响应中提取 `session_id`，后续请求复用该值即可自动加载历史（需注意 1 小时过期限制）。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域限制**：工作流应用调用明确要求华北2（北京）地域，智能体应用虽未明示，但建议统一部署在北京 region 以确保兼容性；
|
||||
- **会话有效期**：`session_id` 有效期为 1 小时，最多支持 50 轮对话；超时或超轮次后需新建会话；
|
||||
- **参数冲突规则**：若请求中同时提供 `session_id` 和 `messages`，系统**优先使用 `messages`**，`session_id` 将被忽略；
|
||||
- **插件参数要求**：自定义插件的输入参数必须在控制台配置为 **“业务透传”** 方式，否则无法通过 `biz_params` 传递；
|
||||
- **SDK 版本依赖**：
|
||||
- Java SDK 推荐 ≥ 2.12.0（文档 1 & 2）；
|
||||
- Python SDK 推荐 ≥ 1.14.0（文档 3 中插件调用所需）；
|
||||
- **错误处理**：所有调用均返回 `request_id`，用于问题排查；常见错误码参考 [开发者参考错误码](https://help.aliyun.com/zh/model-studio/developer-reference/error-code)。
|
||||
- **地域限制**：工作流应用调用仅支持华北2（北京）地域，智能体应用无明确地域限制，但建议与应用部署地域保持一致以降低延迟；
|
||||
- **API Key 安全**：严禁硬编码 API Key，必须通过环境变量或密钥管理服务注入；
|
||||
- **插件参数透传**：仅当应用已关联对应插件且插件参数配置为“业务透传”时生效；插件 ID（`plugin_code`）需从插件卡片获取，不可猜测；
|
||||
- **错误处理**：所有调用均需检查 `status_code`（HTTP）或 `response.status_code`（SDK），失败时解析 `request_id` 和 `message` 并查阅 [错误码文档](https://help.aliyun.com/zh/model-studio/developer-reference/error-code)；
|
||||
- **SDK 版本兼容性**：Java SDK 要求 ≥2.12.0（见 [调用智能体应用](../../raw/application-user-guide/bailian-application-calling/call-single-agent-application.md) 和 [调用工作流应用](../../raw/application-user-guide/bailian-application-calling/invoke-workflow-application.md)），Python SDK 无显式版本要求，但插件参数功能需 ≥1.14.0（见 [应用的自定义参数传递](../../raw/application-user-guide/bailian-application-calling/pass-through-of-application-parameters.md)）；
|
||||
- **响应结构一致性**：无论应用类型，成功响应均含 `output.text` 字段；`usage.models` 中 `model_id` 表明实际执行模型（如 `qwen-max`、`qwen-plus`），可用于计费与性能分析。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,40 +1,49 @@
|
||||
# data connection overview
|
||||
|
||||
数据连接是阿里云百炼平台统一管理外部数据源的核心能力，为应用提供安全、可控的数据接入入口。通过创建不同类型的数据连接器，开发者可将企业自有数据库、文档系统或对象存储中的数据实时接入百炼应用，在对话或智能体执行中按需检索与引用。该能力支持结构化与非结构化数据的混合接入，并兼顾平台托管与流式直连两种模式。
|
||||
数据连接是阿里云百炼平台统一管理外部数据源的核心能力，为应用提供安全、可控的数据接入通道。通过创建不同类型的连接器，开发者可将企业自有数据库、文档系统、对象存储等数据源接入百炼，支撑对话中实时查询、知识检索与智能推理。所有连接器均遵循最小权限原则，支持平台托管与流处理两类架构模式。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
数据连接器按数据访问模式分为两类：**平台托管型**（文件、表格）和**流处理型**（MySQL、PostgreSQL、PolarDB-X 2.0、语雀、OSS）。
|
||||
- **平台托管型**：数据导入百炼平台或自有OSS后，经向量化处理构建知识库，支持语义检索（如 `searchFile`、`searchTable` 工具），适用于静态或低频更新场景。
|
||||
- **流处理型**：数据保留在源端，运行时实时查询（如 MySQL 的 `executeSQL`），适用于高时效性需求；但注意，[原文标题](../../raw/application-user-guide/data-connection-overview/data-connection.md) 明确指出：**仅通过 DMS 导入方式创建的 MySQL/PostgreSQL/PolarDB-X 连接器才支持 SQL 执行**，自定义数据源方式创建的连接器不支持该能力。
|
||||
- 各连接器均支持与智能体（Agent 1.0）及 API 应用集成，调用时可通过 `tags` 参数实现基于标签的过滤检索。
|
||||
数据连接器按数据访问方式分为两类：
|
||||
|
||||
- **平台托管型**：适用于非结构化与结构化静态数据，包括：
|
||||
- **文件连接器**：支持 PDF、Word、Markdown 等格式，依赖[文档理解](https://help.aliyun.com/zh/document-mind/product-overview/overview-of-document-understanding#9a4f5fb91fpps)能力进行[多模态](../concepts/multi-modal.md)解析（如大模型文档解析、Qwen VL 解析）；详情见 [原文标题](../../raw/application-user-guide/data-connection-overview/data-connection.md)。
|
||||
- **表格连接器**：支持 CSV、Excel 等结构化数据，支持 `image_url` 字段类型以生成图片向量索引，用于以图搜图等场景。
|
||||
|
||||
- **流处理型**：适用于实时、动态数据源，支持 SQL 查询（**仅限 DMS 导入方式创建的连接器**）：
|
||||
- **MySQL / PostgreSQL / PolarDB-X 2.0**：需满足特定前置条件（如 PostgreSQL 要求 `wal_level=logical`），连通性检测分别依赖 EventBridge 或 DTS 服务；具体配置差异详见 [原文标题](../../raw/application-user-guide/data-connection-overview/data-connection.md)。
|
||||
- **语雀**：仅支持公网语雀，需提供 Tenant access token。
|
||||
- **OSS**：需开通向量检索服务，并为 Bucket 添加 `bailian-datahub-access` 标签（值为 `read`）；该要求与文件/表格连接器使用的 `bailian-connector-access` 标签不同，注意区分 —— [原文标题](../../raw/application-user-guide/data-connection-overview/data-connection.md) 中明确指出二者标签名与权限值均不一致。
|
||||
|
||||
> **注意**：MySQL、PostgreSQL、PolarDB-X 2.0 连接器均明确说明“仅通过**从DMS导入数据源**方式创建的连接器支持执行SQL查询”，而自定义方式创建的连接器**不支持 SQL 执行**。该限制在三类数据库连接器描述中完全一致，无矛盾。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数类别 | 关键字段 | 说明 |
|
||||
|----------|----------|------|
|
||||
| **通用** | 连接器名称、描述 | 名称需唯一且可识别；描述用于指导模型理解数据用途，影响检索准确率，建议明确数据范围与业务含义。 |
|
||||
| **文件/表格** | 存储位置（平台存储 / 自有OSS） | 平台存储提供免费额度（文件连接器限 200,000 文件 + 1 TB；表格连接器 1 TB 免费），超限转按量付费；自有OSS需添加 `bailian-connector-access` 标签（值 `ReadAndWrite`）[原文标题](../../raw/application-user-guide/data-connection-overview/data-connection.md)。 |
|
||||
| **数据库类** | 网络类型、SLR 授权、wal_level（PostgreSQL）、dbName（PostgreSQL） | MySQL 默认端口 3306，PostgreSQL 必填 `dbName` 且需 `wal_level=logical`；PolarDB-X 2.0 **仅支持私网**，且首次使用需显式授权 `AliyunServiceRoleForSFMConnectorAccessDTS` 和 `AliyunServiceRoleForSFMAccessPolarDBX` 角色 [原文标题](../../raw/application-user-guide/data-connection-overview/data-connection.md)。 |
|
||||
| **语雀/OSS** | Tenant access token（语雀）、Bucket 选择（OSS） | 语雀仅支持公网版本；OSS Bucket 需开通向量检索服务，且必须添加 `bailian-datahub-access` 标签（值 `read`），否则无法使用 `searchOSSFile` 等工具。 |
|
||||
|
||||
> **注意**：文档中关于 OSS Bucket 标签的键名存在不一致——文件/表格连接器要求 `bailian-connector-access`，而 OSS 连接器要求 `bailian-datahub-access`。请严格按对应连接器类型配置，否则授权失败。
|
||||
| **通用** | 连接器名称、描述 | 名称需唯一且易识别；描述影响智能体调用准确度，建议明确数据内容与用途 |
|
||||
| **文件/表格** | 存储位置（平台存储 / 自有 OSS） | 平台存储提供免费额度（文件连接器限 200,000 文件 + 1 TB，表格连接器 1 TB）；自有 OSS 需添加 `bailian-connector-access` 标签（值 `ReadAndWrite`） |
|
||||
| **数据库类** | 数据库地址、端口、用户名、密码、dbName（PostgreSQL/PolarDB-X 必填） | MySQL 默认端口 3306，PostgreSQL 默认 5432；PolarDB-X 2.0 **仅支持私网**，且不支持自建实例 |
|
||||
| **语雀/OSS** | Tenant access token（语雀）、Bucket 选择（OSS） | 语雀 [Token](../concepts/token.md) 需通过[语雀开放 API](https://www.yuque.com/yuque/developer/api) 获取；OSS Bucket 不支持归档/冷归档存储类型 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **创建连接器**：进入 [数据连接](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/connector/list) 控制台 → 单击“创建连接器” → 选择类型 → 填写基本信息与连接参数 → 完成 SLR 授权（如需）→ 测试连通性 → 确认创建。
|
||||
2. **导入数据（仅平台托管型）**：
|
||||
- 文件连接器：在详情页选择类目 → “导入数据” → 本地上传 PDF/Word/Excel 等 → 选择解析方式（推荐“大模型文档解析”以支持图表理解）→ 配置标签（可选）→ 提交。
|
||||
- 表格连接器：在详情页新建数据表 → 选择“直接上传Excel”或“自定义表头” → 上传 CSV/Excel → 注意列名、类型、描述需严格匹配，`image_url` 字段需为公开可访问 URL。
|
||||
3. **调用连接器**：在智能体工作流或 API 请求中，通过预置工具（如 `searchFile`、`executeSQL`）传入 `connectorId` 及查询参数；标签过滤需在请求 `tags` 字段中指定。
|
||||
1. **创建连接器**：进入 [数据连接](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/connector/list) 页面 → 单击 **创建连接器** → 选择类型 → 填写基本信息与连接参数 → （可选）点击 **开始检测** 验证连通性 → 确认创建。
|
||||
2. **导入数据**：
|
||||
- 文件连接器：进入详情页 → 选择类目 → **导入数据** → 本地上传 → 选择解析方式（默认/自定义）→ 配置标签（可选）→ 确认。
|
||||
- 表格连接器：进入详情页 → 在**数据表管理**下新建或选择数据表 → 上传 Excel 或自定义表头（列名、类型必填，结构不可修改）→ 确认导入。
|
||||
3. **调用能力**：连接器创建并导入数据后，可在智能体应用中通过内置工具（如 `searchOSSFile`、`searchTableData`）或 RAG 检索链路调用数据；具体工具使用请参考对应连接器的 API 文档。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **容量与时效**：平台托管文件仅保留最近 90 天导入记录（不可查看但未删除）；文件解析可能因高峰排队延迟数小时，偶发超时需重试。
|
||||
- **格式限制**：文件连接器**不支持直接导入 JSON/CSV/YAML**，需先转为 XLSX/XLS；表格连接器上传文件结构必须与定义的表结构完全一致，否则失败。
|
||||
- **权限与网络**：RAM 用户需主账号授予数据连接管理权限；数据库连接需确保白名单包含百炼服务 IP 段（如公网需加 `100.64.0.0/16`），私网连接需同地域且网络互通。
|
||||
- **OSS 特殊要求**：不支持归档/冷归档存储类型；若 Bucket 开启 Referer 防盗链，须将 `*.console.aliyun.com` 加入白名单。
|
||||
- **功能差异**：MySQL/PostgreSQL/PolarDB-X 的 SQL 执行能力**强依赖 DMS 导入方式**，自定义方式创建的连接器仅支持元数据同步，不可执行查询——此限制在 [原文标题](../../raw/application-user-guide/data-connection-overview/data-connection.md) 中多次强调，开发时务必确认创建路径。
|
||||
- **权限要求**：RAM 用户需主账号授予数据连接管理权限；首次使用 OSS、DMS、PolarDB-X 等服务时，需完成 SLR 授权（如 `AliyunServiceRoleForSFMConnectorAccessDTS`）。
|
||||
- **网络限制**：
|
||||
- MySQL 支持公网/私网，但公网需将指定 IP 段加入白名单；
|
||||
- PolarDB-X 2.0 **仅支持私网**，且必须与百炼服务同地域；
|
||||
- PostgreSQL 自建实例需配置 `listen_addresses` 允许 `100.64.0.0/16` 网段访问。
|
||||
- **数据时效性**：平台托管型（文件/表格）导入后生成独立副本，与原始数据无关联；流处理型（数据库/OSS/语雀）为实时访问，无缓存。
|
||||
- **文件限制**：文件连接器仅支持最近 90 天内导入的文件预览；不支持直接导入 JSON/CSV/YAML，需转为 XLSX/XLS 后再导入。
|
||||
- **标签差异**：OSS 连接器要求 Bucket 标签为 `bailian-datahub-access: read`，而文件/表格连接器要求 `bailian-connector-access: ReadAndWrite` —— 二者不可混用。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,72 +1,69 @@
|
||||
# fine tuning
|
||||
|
||||
fine tuning 是阿里云百炼平台提供的核心模型优化能力，允许开发者基于自有数据对预训练大模型进行定制化训练，以提升其在特定业务场景、领域知识或安全合规要求下的表现。该能力覆盖文本生成、视觉理解、语音合成、图像生成、视频生成及强化学习等多种模态与任务类型，支持高效微调（LoRA）、全参微调、持续预训练（CPT）和直接偏好优化（DPO）等多种训练范式，适用于从快速验证到生产部署的全生命周期。
|
||||
fine tuning（微调）是百炼平台提供的核心模型优化能力，允许开发者基于自有数据对预训练大模型进行定制化训练，从而提升其在特定业务场景、领域知识或风格表达上的表现。它适用于文本生成、视觉理解、语音合成、图像/视频生成等多种模态，支持 SFT（监督微调）、CPT（持续预训练）、DPO（直接偏好优化）及 RL（强化学习）等多种训练范式。所有微调任务均需在华北2（北京）地域执行，并依赖 DashScope API Key 和相应 RAM 权限。
|
||||
|
||||
## 支持的模型与功能
|
||||
|
||||
百炼平台支持多模态、多任务的 fine tuning，不同模型类型对应不同的训练方式与适用场景：
|
||||
百炼平台支持[多模态](../concepts/multi-modal.md)、多粒度的微调能力：
|
||||
|
||||
- **文本生成模型**：支持 SFT（监督微调）、CPT（持续预训练）和 DPO（直接偏好优化），覆盖 Qwen3 系列、Qwen2.5 系列及千问-Plus-Character 等数十种模型。其中，SFT 用于教会模型执行特定任务（如客服流程、代码范式），CPT 用于注入领域知识（如金融术语、法律条文），DPO 用于对齐人类偏好（如拒有害建议、答干脆利落）[原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-text-generation-model/model-training-overview.md)。
|
||||
|
||||
- **视觉理解模型（千问VL）**：支持 SFT 和 DPO，需遵循 ChatML 格式并支持图像/视频嵌入；训练数据中 `system` 消息的 `content` 必须为数组格式（如 `[{"text":"..."}]`），且图片/视频文件名需全局唯一、位于 ZIP 包根目录下 [原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-text-generation-model/model-training-on-console.md)。
|
||||
- **文本生成模型**：覆盖 Qwen 系列（如 `qwen3-8b`、`qwen3.5-9b`、`qwen3-vl-8b-instruct`）及千问 Plus/Flash 等变体，支持 CPT、SFT（全参/LoRA）、DPO（全参/LoRA）三种方式 [原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-text-generation-model/model-training-overview.md)。
|
||||
- **视觉生成模型**：图像生成（文生图/图生图）支持 `wan2.7-image-pro`、`wan2.7-image`；视频生成（图生视频）支持 `wan2.7-i2v`、`wan2.2-kf2v-flash` 等，均采用 SFT-LoRA 高效微调 [原文标题](../../raw/model-user-guide/fine-tuning/wan-image-generation-finetune-guide.md)。
|
||||
- **语音合成模型**：仅支持 `cosyvoice-v3-flash` 的 SFT 高效微调（`efficient_sft`），用于同一发音人的高还原度音色定制，**控制台暂不支持，必须通过 API 发起** [原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-speech-synthesis-model/fine-tune-speech-synthesis-model-by-api.md)。
|
||||
- **强化学习（RL）训练**：面向 Agent 场景（如工具调用、数学推理），支持 `qwen3.5-9b` 等 MoE/非 MoE 模型，需通过 MTU 训练单元计费，不支持 [Token](../concepts/token.md) 计费 [原文标题](../../raw/model-user-guide/fine-tuning/rl-training-overview.md)。
|
||||
|
||||
- **图像生成模型（万相）**：仅支持 SFT-LoRA 高效微调，当前限华北2（北京）地域，适用模型包括 `wan2.7-image-pro` 和 `wan2.7-image`，支持文生图（t2i）与图生图（i2i）两种模式 [原文标题](../../raw/model-user-guide/fine-tuning/wan-image-generation-finetune-guide.md)。
|
||||
|
||||
- **视频生成模型（万相）**：同样限北京地域，支持 `wan2.7-i2v`、`wan2.5-i2v-preview`、`wan2.2-i2v-flash`（首帧驱动）及 `wan2.2-kf2v-flash`（首尾帧驱动）等模型，采用 SFT-LoRA 方式，需指定 `generation_type` 对应的超参（如 `n_epochs`、`batch_size`）[原文标题](../../raw/model-user-guide/fine-tuning/wan-video-generation-finetune-guide.md)。
|
||||
|
||||
- **语音合成模型（CosyVoice）**：仅支持 `cosyvoice-v3-flash` 的 `efficient_sft` 微调，面向同一发音人多小时录音的高还原度音色定制，产物为独立部署的单音色模型，调用时 `voice` 参数固定为 `default` [原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-speech-synthesis-model/fine-tune-speech-synthesis-model-by-api.md)。
|
||||
|
||||
- **强化学习（RL）训练**：面向 Agent 场景（如工具调用、数学推理），需通过模型训练单元（MTU）计费，不支持按 [Token](../concepts/token.md) 计费；当前支持 `qwen3.5-9b` 等非 MoE 模型及 `qwen3.6-flash` 等 MoE 模型，需联系商务经理开通权限 [原文标题](../../raw/model-user-guide/fine-tuning/rl-training-overview.md)。
|
||||
|
||||
> **注意**：文档 4 与文档 5 均指出“推荐您以先 CPT（可选），后 SFT，再 DPO 的顺序使用模型调优”，但文档 3 的 RL 训练流程图明确将 RL 列为可选的最终环节（`CPT→SFT→DPO→RL`）。实际工程中，RL 通常在 SFT/DPO 后引入，用于端到端策略优化，而非替代 DPO。此处以 RL 文档为准，因其专述 RL 流程。
|
||||
> **注意**：文档 4 与文档 5 均列出 SFT 支持模型，但文档 4 明确标注 `Qwen3.7-Plus-2026-05-26` 调优后部署需联系商务经理，而文档 5 未提及此限制；实际使用前应以最新控制台可选模型为准，避免因版本变更导致部署失败。
|
||||
|
||||
## 关键参数
|
||||
|
||||
不同训练方式与模型类型的关键参数存在显著差异，开发者需按场景选择：
|
||||
不同训练类型和模型对应的核心超参存在显著差异：
|
||||
|
||||
- **通用超参（文本/SFT）**：`learning_rate`（SFT 推荐 `1e-4` 量级，CPT 推荐 `1e-5`）、`n_epochs`（数据 <10k 条时设 3~5，>10k 条时设 1~2）、`batch_size`（默认 16/32）、`lora_rank`（LoRA 秩，默认 8，图像/视频任务常设 32）、`eval_steps`（默认 50）[原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-text-generation-model/model-training-on-console.md)。
|
||||
|
||||
- **图像/视频生成专用参数**：
|
||||
- 图像：`max_pixels`（如 `"2k"` 表示 2048×2048）、`val_img_size`（验证图分辨率）、`max_token_length`（如 `"2k"`）必须保持一致；`generation_type` 必填 `"t2i"` 或 `"i2i"` [原文标题](../../raw/model-user-guide/fine-tuning/wan-image-generation-finetune-guide.md)。
|
||||
- 视频：`max_pixels` 为整数（如 `102400`），`n_epochs` 与 `batch_size` 强耦合（steps = n_epochs × ⌈数据集大小 / batch_size⌉），`eval_epochs` 需 ≥ `n_epochs/10` [原文标题](../../raw/model-user-guide/fine-tuning/wan-video-generation-finetune-guide.md)。
|
||||
|
||||
- **语音合成（CosyVoice）专用参数**：分为 LM（影响韵律）与 FM（影响音色）两套子参数，如 `lm_max_epoch=60`、`fm_max_epoch=100`，`*_step` 控制 Checkpoint 保存间隔，`*_num` 控制保留数量，组合后候选模型数为 `lm_num × fm_num` [原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-speech-synthesis-model/fine-tune-speech-synthesis-model-by-api.md)。
|
||||
|
||||
- **强化学习（RL）专用参数**：`algorithm="gspo"`、`batch_size=64`、`kl_loss_coef=0.002`、`n_rollouts=8` 等 11 项必填超参，需严格匹配基座模型类型（如 `qwen3.5-9b` 非 MoE 模型）[原文标题](../../raw/model-user-guide/fine-tuning/rl-training-overview.md)。
|
||||
- **通用 SFT 参数（API/控制台）**：`learning_rate`（推荐 LoRA 为 `1e-4` 量级，全参为 `1e-5`）、`n_epochs`（数据 <10k 条建议 3–5 轮）、`batch_size`（默认值因模型而异，常见为 16/32）、`eval_steps`（默认 50）、`lora_rank`（LoRA 秩，默认 8，图像/视频任务常设为 32）[原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-text-generation-model/model-training-on-console.md)。
|
||||
- **图像/视频生成专用参数**：`max_pixels`（训练图最大像素总数，如 `"2k"` 表示 2048×2048）、`val_img_size`（验证图分辨率）、`generation_type`（`"t2i"` 或 `"i2i"`）、`lora_alpha`（视频任务中与 `lora_rank` 同时设置，推荐 32）。
|
||||
- **CosyVoice 专用参数**：解耦为 LM（语言模型）与 FM（流匹配模型）两组，关键字段包括 `lm_max_epoch`（推荐 60）、`fm_max_epoch`（推荐 100）、`lm_batch_size`（推荐 1000）、`fm_batch_size`（推荐 2000），直接影响音色还原度与韵律表现。
|
||||
- **RL 训练参数**：`algorithm`（如 `"gspo"`）、`batch_size`（如 64）、`kl_loss_coef`（KL 散度系数，如 `0.002`）、`n_rollouts`（每样本采样次数，如 8），需严格匹配基座模型规格。
|
||||
|
||||
## 使用方式
|
||||
|
||||
fine tuning 通过 API、命令行或控制台三种方式发起，流程高度统一：上传数据 → 创建任务 → 查询状态 → 部署模型 → 调用服务。
|
||||
微调流程统一为四步：准备数据 → 上传文件 → 创建任务 → 部署调用。
|
||||
|
||||
- **数据上传**：所有方式均需先将训练数据（ZIP 或 JSONL）上传至百炼平台获取 `file_id`。ZIP 包需满足：`data.jsonl` 位于根目录、图片/音频文件名全局唯一、单文件 ≤300MB（API）或 2GB（控制台）[原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-text-generation-model/fine-tuning-api-guide.md)。
|
||||
1. **数据准备**：
|
||||
- 文本 SFT：使用 ChatML 格式 JSONL 文件（`{"messages": [...]}`），`data.jsonl` 必须位于 ZIP 包根目录；视觉/语音任务需按指定目录结构打包（如 `user_data/data.jsonl` + `user_data/train/*.wav`）。
|
||||
- 图像/视频：ZIP 包内图片尺寸 ≤1024px，格式支持 JPG/PNG/WEBP；视频需满足时长与大小限制（如 `qwen3.5` 系列视频 ≤2GB）。
|
||||
- CosyVoice：音频为 WAV 格式，采样率 ≥16kHz，总时长建议 1–10 小时，单条 2–30 秒。
|
||||
|
||||
- **任务创建**：
|
||||
- **API/CLI**：通过 `POST /api/v1/fine-tunes` 提交，需指定 `model`、`training_datasets`（含 `file_id`）、`training_type`（如 `"sft"`、`"efficient_sft"`）及 `hyper_parameters`。CosyVoice 等部分模型仅支持 API [原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-speech-synthesis-model/fine-tune-speech-synthesis-model-by-api.md)。
|
||||
- **控制台**：在[模型调优](https://bailian.console.aliyun.com/?tab=model#/efm/model_manager)页面可视化配置，支持实时摘要预览，但 CosyVoice、RL 等高级功能暂未开放控制台入口。
|
||||
2. **上传文件**：
|
||||
```bash
|
||||
curl -X POST 'https://dashscope.aliyuncs.com/api/v1/files' \
|
||||
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
|
||||
-F 'files=@train_data.zip' \
|
||||
-F 'purpose="fine-tune"'
|
||||
```
|
||||
返回 `file_id` 用于后续任务创建。
|
||||
|
||||
- **状态查询与日志**：通过 `GET /api/v1/fine-tunes/{job_id}` 轮询，`status` 为 `"SUCCEEDED"` 后提取 `finetuned_output`（新模型名）；RL 训练需额外通过 `AgenticRL.logs()` 查看 Reward 曲线 [原文标题](../../raw/model-user-guide/fine-tuning/rl-training-overview.md)。
|
||||
3. **创建任务**：
|
||||
- 文本/视觉：通过 `/api/v1/fine-tunes` 提交，指定 `model`、`training_datasets`（含 `file_id`）、`training_type`（如 `"efficient_sft"`）及 `hyper_parameters`。
|
||||
- CosyVoice：仅支持 API，且 `training_file_ids` 仅接受单个 ID，`hyper_parameters` 必填全部 8 个 LM/FM 字段。
|
||||
- RL：需先部署 Rollout/Reward 函数，再通过 `AgenticRL.run()` 提交，依赖 MTU 资源配置。
|
||||
|
||||
- **模型部署与调用**：
|
||||
- 部署：调用 `POST /api/v1/deployments`，传入 `model_name`（即 `finetuned_output`）及 `plan="lora"`（LoRA 模型）。
|
||||
- 调用：使用 `deployed_model` 名称发起推理请求。注意：图像生成模型仅支持异步调用，且响应中 `message.content` 无 `type` 字段 [原文标题](../../raw/model-user-guide/fine-tuning/wan-image-generation-finetune-guide.md)。
|
||||
4. **部署与调用**：
|
||||
- 查询任务状态直至 `status` 为 `SUCCEEDED`，获取 `finetuned_output`。
|
||||
- 调用 `/api/v1/deployments` 部署，`plan` 设为 `"lora"`（LoRA 模型）或 `"full"`（全参模型）。
|
||||
- 部署成功（`status` 为 `RUNNING`）后，使用 `deployed_model` 名称调用对应服务（如图像生成需带 `X-DashScope-Async: enable` 头）。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域与权限限制**：图像/视频生成、CosyVoice 及部分 RL 功能**仅限华北2（北京）地域**；子账号需显式授予模型调用、训练、部署权限，且 RL 训练必须通过 MTU 计费（不支持 [Token](../concepts/token.md) 计费）[原文标题](../../raw/model-user-guide/fine-tuning/wan-image-generation-finetune-guide.md)。
|
||||
|
||||
- **数据与格式限制**：
|
||||
- 图像训练：单张图宽高均 >10px，长宽比 ≤200:1，推荐 ≤8K 分辨率；ZIP 包内图片尺寸 ≤1024px [原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-text-generation-model/model-training-on-console.md)。
|
||||
- 语音训练：音频必须为 `.wav` 格式、采样率 ≥16kHz、单条时长 1~30 秒；`data.jsonl` 中 `wav_fn` 必须带 `train/` 前缀，`text` 为纯文本（禁用 SSML/LaTeX）[原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-speech-synthesis-model/fine-tune-speech-synthesis-model-by-api.md)。
|
||||
- RL 训练：数据量至少大于 `batch_size`，起步几十条即可验证；Demo 默认使用精简数据集 `calc_train_min.jsonl` 以避免资源浪费 [原文标题](../../raw/model-user-guide/fine-tuning/rl-training-overview.md)。
|
||||
|
||||
- **计费与成本**：
|
||||
- 文本/SFT：按训练 [Token](../concepts/token.md) 总数计费，单价因模型而异（如 `qwen3-8b` ¥0.006/千Token）；高效训练（LoRA）与全参训练单价相同，但 LoRA 更快更省 [原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-text-generation-model/model-training-overview.md)。
|
||||
- CosyVoice：训练费 ¥0.2/千Tokens，部署费按模型单元时长计费；最小化超参（`lm_max_epoch=4`）实测耗时约 37 分钟，推荐超参成本约为其 20 倍 [原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-speech-synthesis-model/fine-tune-speech-synthesis-model-by-api.md)。
|
||||
- RL：按 MTU 单元计费（IV 型预付费 ¥19,914/月/实例），无 Token 计费选项 [原文标题](../../raw/model-user-guide/fine-tuning/rl-training-overview.md)。
|
||||
|
||||
- **效果与风险**：
|
||||
- 过拟合风险：训练损失持续下降但验证损失上升时，需减少 `n_epochs` 或 `lora_rank`；欠拟合则反之 [原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-text-generation-model/enhance-the-security-compliance-of-large-models.md)。
|
||||
- 能力边界：调优无法扩展基础模型能力（如 CosyVoice 无法通过训练支持新语种；图像模型无法提升原生分辨率上限）[原文标题](../../raw/model-user-guide/fine-tuning/fine-tune-speech-synthesis-model/fine-tune-speech-synthesis-model-by-api.md)。
|
||||
- **地域与权限**：所有微调任务**仅限华北2（北京）地域**，且子账号需显式授予模型调用、训练、部署权限 [原文标题](../../raw/model-user-guide/fine-tuning/wan-image-generation-finetune-guide.md)。
|
||||
- **计费模式**：
|
||||
- 文本/视觉微调：按训练消耗 [Token](../concepts/token.md) 数计费（单价见模型文档），[Token](../concepts/token.md) 数 = 数据 Token 总数 × 循环次数。
|
||||
- CosyVoice：训练费 0.2 元/千 Token，部署费按模型单元时长计费。
|
||||
- RL 训练：**强制使用 MTU 训练单元（预付费/后付费）**，不支持 Token 计费。
|
||||
- **数据与格式约束**：
|
||||
- 图像分辨率上限为 8K，但超过 4K 仅支持 JPG/PNG；视频帧列表模式要求 `qwen3.5+` VL 模型。
|
||||
- CosyVoice 训练数据必须为**同一发音人**，混合多人会导致音色失真；`text` 字段禁止含 SSML/LaTeX 标签。
|
||||
- **能力边界**：
|
||||
- 微调无法扩展基础模型能力（如 CosyVoice 不支持新语种，万相模型无法新增特效类型）。
|
||||
- LoRA 微调产物为轻量级适配器，部署后模型名固定（如 `xxx-ft-xxxx`），不可切换音色或风格。
|
||||
- **调试建议**：首次训练推荐使用精简数据集快速验证链路；关注 `Training Loss` 与 `Validation Loss` 曲线判断欠拟合/过拟合；RL 训练需紧盯 `critic/rewards/mean` 指标趋势。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,73 +1,83 @@
|
||||
# get started with models
|
||||
|
||||
阿里云百炼提供开箱即用的大模型服务，支持通过兼容 OpenAI 的 API 快速调用千问（Qwen）全系列及主流第三方模型。开发者无需自行部署或运维模型，只需配置 API Key 和 Base URL 即可发起首次请求。本文档面向开发者，聚焦模型调用的核心路径，涵盖模型选择、参数配置、接入方式及关键限制。
|
||||
阿里云百炼提供开箱即用的大模型服务，支持通过兼容 OpenAI 的 API 快速调用千问（Qwen）全系列及主流第三方模型。开发者无需自行部署或运维，只需配置 API Key 和 Base URL 即可发起首次请求。平台同时支持可视化应用构建与高代码开发模式，覆盖从快速验证到生产部署的完整链路。
|
||||
|
||||
## 支持的模型与功能
|
||||
|
||||
百炼提供覆盖多模态与多场景的模型服务，核心文本生成模型按能力与成本分层：
|
||||
百炼提供[多模态](../concepts/multi-modal.md)、多场景的模型服务，核心包括：
|
||||
|
||||
- **Qwen Max**：效果最优，适合复杂多步骤任务（如 `qwen3.7-max`）；
|
||||
- **Qwen Plus**：效果、速度与成本均衡，是多数生产场景的**推荐选择**（如 `qwen3.7-plus`）；
|
||||
- **Qwen Flash**：高性价比、低延迟，适用于简单响应类任务（如 `qwen3.7-flash`）。
|
||||
- **千问（Qwen）系列**：按能力与成本分层，推荐选择 `qwen3.7-plus`（效果、速度、成本均衡），`qwen3.7-max`（复杂任务首选），`qwen3.7-flash`（低延迟简单任务）；[最新模型列表详见](../../raw/model-user-guide/get-started-with-models/models.md)。
|
||||
- **第三方模型**：集成 DeepSeek、Kimi、GLM 等，其中 DeepSeek 仅支持华北2（北京）地域 [原文标题](../../raw/model-user-guide/get-started-with-models/what-is-model-studio.md)。
|
||||
- **[多模态](../concepts/multi-modal.md)能力**：覆盖文本生成、视觉理解、图像/视频生成、语音识别与合成、嵌入向量等。
|
||||
- **领域模型**：提供长文本处理、法律、意图理解、角色扮演等细分场景专用模型。
|
||||
|
||||
此外支持 DeepSeek、Kimi、GLM 等第三方模型，以及长文本、法律、意图理解等细分领域模型。所有模型均支持文本生成、嵌入向量、多轮对话等基础能力；部分模型还支持视觉理解、图像生成等扩展能力 [什么是阿里云百炼](../../raw/model-user-guide/get-started-with-models/what-is-model-studio.md)。
|
||||
|
||||
> **注意**：文档 3（`models.md`）中列出的 `qwen3.8-max-preview` 标注“仅 [Token](../concepts/token.md) Plan 可用”，但文档 1（`what-is-model-studio.md`）和文档 6（`rate-limit.md`）均未提及该模型在通用调用路径中的可用性，且其限流数据缺失。建议以控制台实时模型市场为准，避免依赖预览版 ID。
|
||||
> **注意**：文档中 `qwen3.8-max-preview` 标注“仅 [Token](../concepts/token.md) Plan 可用”，但该模型未在限流文档（[原文标题](../../raw/model-user-guide/get-started-with-models/rate-limit.md)）中列出限流值，且其命名与当前主流 `qwen3.7-*` 系列不一致，建议优先使用已明确限流策略的 `qwen3.7-max` 或 `qwen3.7-plus`。
|
||||
|
||||
## 关键参数
|
||||
|
||||
调用模型必需以下三个参数，且必须严格匹配同一地域与计费方案：
|
||||
### Base URL
|
||||
必须与对应计费方案和地域的 API Key 配套使用，否则返回 401 错误。三类域名适用场景不同：
|
||||
- **业务空间专属域名**（推荐生产环境）：`https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1`，提供更高吞吐、更低时延与流量隔离；
|
||||
- **Dashscope 域名**（兼容存量）：如 `https://dashscope.aliyuncs.com/compatible-mode/v1`（北京）、`https://dashscope-us.aliyuncs.com/compatible-mode/v1`（美国）；
|
||||
- **试用域名**（仅限快速验证）：`https://trial.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`，RPM 限流为 1000，不建议用于生产 [原文标题](../../raw/model-user-guide/get-started-with-models/base-url.md)。
|
||||
|
||||
- **API Key**：在[API Key 管理页面](https://bailian.console.aliyun.com/?tab=model#/api-key)创建，**各地域独立，不可跨地域复用**；
|
||||
- **Base URL**：决定接入点与服务保障等级，需与 API Key 所属地域及计费类型一致；
|
||||
- **Model ID**：如 `qwen3.7-plus`，必须与 Base URL 所支持的模型列表一致（例如 `qwen3.7-max-preview` 仅在 [Token](../concepts/token.md) Plan 域名下可用）。
|
||||
> **注意**：各地域 API Key 不通用，且 `WorkspaceId` 仅在华北2（北京）、新加坡、日本（东京）、德国（法兰克福）地域需显式填入；美国（弗吉尼亚）使用 `dashscope-us.aliyuncs.com`，无需 `WorkspaceId` [原文标题](../../raw/model-user-guide/get-started-with-models/regions.md)。
|
||||
|
||||
Base URL 分为三类：
|
||||
- **业务空间专属域名**（推荐）：`https://{WorkspaceId}.{region}.maas.aliyuncs.com/...`，需先在[业务空间管理](https://bailian.console.aliyun.com/cn-beijing?tab=globalset#/efm/business_management)获取 WorkspaceId，提供更高并发与 SLA（99.9%）；
|
||||
- **Dashscope 域名**：如 `https://dashscope.aliyuncs.com/...`，兼容存量代码，但已不推荐用于新生产环境；
|
||||
- **试用域名**：如 `https://trial.cn-beijing.maas.aliyuncs.com/...`，仅限快速验证，RPM 限流为 1000，**不提供 SLA** [地域及接入域名](../../raw/model-user-guide/get-started-with-models/regions.md)。
|
||||
### API Key
|
||||
- 通过 [API Key 页面](https://bailian.console.aliyun.com/?tab=model#/api-key) 创建；
|
||||
- 建议配置为环境变量 `DASHSCOPE_API_KEY`，避免硬编码泄露风险 [原文标题](../../raw/model-user-guide/get-started-with-models/first-api-call-to-qwen.md)。
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 1. 环境准备
|
||||
- 注册阿里云账号并完成实名认证；
|
||||
- 开通百炼服务，在控制台创建 API Key；
|
||||
- （北京/新加坡/东京/法兰克福地域）获取业务空间 ID（WorkspaceId）；
|
||||
- 将 `DASHSCOPE_API_KEY` 配置为环境变量，避免硬编码 [首次调用千问API](../../raw/model-user-guide/get-started-with-models/first-api-call-to-qwen.md)。
|
||||
- 开通百炼服务，在控制台创建 API Key 并获取 `WorkspaceId`（如需）；
|
||||
- 安装 SDK：`pip install -U openai`（OpenAI 兼容）或 `pip install -U dashscope`（DashScope SDK）。
|
||||
|
||||
### 2. SDK 调用示例（OpenAI 兼容）
|
||||
### 2. 发起请求（OpenAI 兼容示例）
|
||||
```python
|
||||
import os
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
api_key=os.getenv("DASHSCOPE_API_KEY"),
|
||||
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1", # 替换为实际 WorkspaceId
|
||||
)
|
||||
|
||||
response = client.chat.completions.create(
|
||||
completion = client.chat.completions.create(
|
||||
model="qwen3.7-plus",
|
||||
messages=[{"role": "user", "content": "你是谁？"}],
|
||||
messages=[{"role": "user", "content": "你是谁？"}]
|
||||
)
|
||||
print(response.choices[0].message.content)
|
||||
print(completion.choices[0].message.content)
|
||||
```
|
||||
|
||||
支持 Python（OpenAI/DashScope SDK）、Node.js、curl 等多种方式，详见各语言示例 [什么是阿里云百炼](../../raw/model-user-guide/get-started-with-models/what-is-model-studio.md)。
|
||||
### 3. 多地域适配
|
||||
- 北京：`{WorkspaceId}.cn-beijing.maas.aliyuncs.com`
|
||||
- 新加坡：`{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com`
|
||||
- 美国（弗吉尼亚）：`dashscope-us.aliyuncs.com`（无 WorkspaceId）
|
||||
- 德国/日本：同理替换 `{region}`，详见 [地域及接入域名](../../raw/model-user-guide/get-started-with-models/regions.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域隔离**：各地域（北京、新加坡、美国弗吉尼亚、德国法兰克福、日本东京）的 API Key、Base URL、模型列表、限流策略完全独立，**严禁混用**；
|
||||
- **限流规则**：按主账号维度合并计算所有子账号、业务空间和 API Key 的调用量。主要限制为 RPM（每分钟请求数）和 TPM（每分钟 [Token](../concepts/token.md) 消耗），超出即返回 429 错误。稳定版模型（如 `qwen3.7-plus`）限流额度远高于快照版（如 `qwen-plus-2025-07-28`）；
|
||||
- **Token Plan 与 Coding Plan 专用性**：Token Plan 和 Coding Plan 订阅用户必须使用其专属 Base URL（如 `https://token-plan.cn-beijing.maas.aliyuncs.com/...`）和专属 API Key，**不可与按量付费 Key 混用**，否则报错 401；
|
||||
- **免费额度控制**：新用户在北京地域享有免费额度，用尽后已认证用户自动转为按量付费；如需避免意外扣费，务必开启[免费额度用完即停](https://help.aliyun.com/zh/model-studio/new-free-quota#d1cb80ac11i92)开关；
|
||||
- **批量推理限制**：仅华北2（北京）和新加坡地域支持批量推理（Batch API），美国、德国、日本地域当前不支持 [地域及接入域名](../../raw/model-user-guide/get-started-with-models/regions.md)。
|
||||
### 限流规则
|
||||
- **账号级聚合**：主账号下所有 RAM 子账号、业务空间、API Key 的调用量合并计算；
|
||||
- **双维度限流**：每分钟请求数（RPM）与每分钟 [Token](../concepts/token.md) 消耗（TPM），任一超限即拒绝请求；
|
||||
- **典型值**（华北2 北京）：
|
||||
- `qwen3.7-plus`：RPM 30,000 / TPM 5,000,000；
|
||||
- `qwen3.7-max-preview`：RPM 60 / TPM 500,000；
|
||||
- **瞬时保护**：即使未达分钟上限，短时请求激增也可能触发 `Request rate increased too quickly` [原文标题](../../raw/model-user-guide/get-started-with-models/rate-limit.md)。
|
||||
|
||||
### 其他关键限制
|
||||
- **地域隔离**：各地域模型、API Key、Base URL 互不通用，跨地域调用必失败；
|
||||
- **功能差异**：批量推理、模型调优、应用开发等功能仅在华北2（北京）和新加坡地域支持，美国、德国、日本地域部分功能缺失 [原文标题](../../raw/model-user-guide/get-started-with-models/regions.md)；
|
||||
- **费用控制**：模型推理与知识库（RAG）计费独立，前者按 [Token](../concepts/token.md) 用量，后者按规格时长，不支持通用节省计划抵扣 [原文标题](../../raw/model-user-guide/get-started-with-models/what-is-model-studio.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [什么是阿里云百炼](../../raw/model-user-guide/get-started-with-models/what-is-model-studio.md)
|
||||
- [首次调用千问API](../../raw/model-user-guide/get-started-with-models/first-api-call-to-qwen.md)
|
||||
- [选择模型](../../raw/model-user-guide/get-started-with-models/models.md)
|
||||
- [地域及接入域名](../../raw/model-user-guide/get-started-with-models/regions.md)
|
||||
- [Base URL总览](../../raw/model-user-guide/get-started-with-models/base-url.md)
|
||||
- [限流](../../raw/model-user-guide/get-started-with-models/rate-limit.md)
|
||||
- [地域及接入域名](../../raw/model-user-guide/get-started-with-models/regions.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,64 +1,49 @@
|
||||
# [knowledge](../api/knowledge.md) base
|
||||
|
||||
知识库是阿里云百炼平台提供的 RAG（[检索增强生成](../concepts/rag.md)）核心能力，用于为大语言模型注入私有、结构化或非结构化数据，提升其在垂直领域问答的准确性与时效性。它支持文档、表格、图片、音视频等多模态数据源，并通过向量化、语义检索、重排与生成协同工作。知识库功能**仅在中国站华北2（北京）地域可用**，其他地域（如新加坡、法兰克福）暂不支持 [知识库 (raw/application-user-guide/knowledge-base/rag-knowledge-base.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base.md)。
|
||||
知识库是阿里云百炼平台提供的 RAG（[检索增强生成](../concepts/rag.md)）核心能力，用于为大语言模型注入私有、领域专属或时效性强的结构化与非结构化数据，从而提升回答的准确性、专业性与事实一致性。其本质是将用户数据通过解析、切片、向量化、索引与语义检索等环节，构建可被大模型动态引用的外部知识源。所有知识库功能仅在中国站华北2（北京）地域可用。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **支持的模型类型**：
|
||||
- 预置模型：千问系列（QwQ/Long/Max/Plus/Turbo/Coder/Deep-Research）、千问VL系列（Max/Plus/Flash/OCR）、Qwen3/Qwen2.5/Qwen2 等开源版；
|
||||
- 第三方模型：DeepSeek-R1、DeepSeek-V3.1、abab6.5s、Llama3.1、Yi-Large 等；
|
||||
- 自定义调优模型（基于上述基座模型微调）[知识库 (raw/application-user-guide/knowledge-base/rag-knowledge-base.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base.md)。
|
||||
> **注意**：文档1中列出的“千问-Plus/Turbo”等重复项属冗余表述，实际以控制台应用创建页可选模型为准，且列表持续更新。
|
||||
知识库支持与多种预置及自定义模型协同工作。**预置模型**包括千问全系（QwQ/Long/Max/Plus/Turbo/Coder/Deep-Research、VL-Max/Plus/Flash/OCR、Qwen3/Qwen2.5/Qwen2 等）及主流第三方模型（DeepSeek-R1、Llama3.1、Yi-Large 等）。**自定义模型**指在百炼平台基于上述基座调优后的模型，同样完全兼容 [知识库 (raw/application-user-guide/knowledge-base/rag-knowledge-base.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base.md)。
|
||||
|
||||
- **核心功能**：
|
||||
- 多模态检索：支持文本、PDF/DOCX（含图表）、图片（OCR+视觉理解）、音视频（ASR+帧提取+剧情解析）；
|
||||
- 检索服务：提供单库/多库联合检索、Query改写、混合检索（向量+关键词）、Rerank精排；
|
||||
- 问答服务：集成智能问答（极速/多轮Agentic模式）、NL2SQL、图文并茂回复、文件预解析；
|
||||
- 知识管理：支持元数据抽取、标签过滤、切片编辑/新增/删除（音视频类仅支持删除）[RAG效果优化 (raw/application-user-guide/knowledge-base/rag-optimization.md)](../../raw/application-user-guide/knowledge-base/rag-optimization.md)。
|
||||
知识库提供三大核心服务形态：
|
||||
- **知识检索**：面向开发者，支持单库/多库联合检索（最多 15 个），提供 Query 改写、混合检索（向量+关键词）、Rerank 排序及精细化参数控制；
|
||||
- **知识问答**：面向终端用户，自动整合检索结果与大模型生成能力，支持极速模式（单轮）与多轮智能模式（Agentic 规划），并具备文件预解析、拒答、防泄漏、[多模态](../concepts/multi-modal.md)回复与引用溯源等生产级功能；
|
||||
- **知识库 API**：提供完整的 SDK 与 RESTful 接口，支持知识库全生命周期管理（创建、上传、索引、检索），但需注意 [知识库API指南 (raw/application-user-guide/knowledge-base/rag-knowledge-base-api-guide.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-api-guide.md) 明确指出该 API **仅适用于文档搜索类知识库**，其他类型（如数据查询、图片问答）暂不支持。
|
||||
|
||||
> **注意**：文档 1 中列出的“千问-开源版（Qwen3、Qwen2.5、Qwen2等）”在文档 6 的模型调用费用部分被具体化为 `qwen3.6-plus`、`qwen3.7-plus` 等版本，且明确其作为问答生成模型计费。这表明模型命名存在版本演进，实际选型应以控制台或模型市场中最新可用版本为准，而非文档中的泛称。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数类别 | 参数名 | 取值范围 | 说明 |
|
||||
|----------|--------|----------|------|
|
||||
| **检索控制** | 相似度阈值 | 0.01–1.0 | 过滤重排后低分切片；过高易漏召，过低引入噪声。默认值需结合命中测试调整 [RAG效果优化 (raw/application-user-guide/knowledge-base/rag-optimization.md)](../../raw/application-user-guide/knowledge-base/rag-optimization.md)。 |
|
||||
| | 初步向量检索 TopK | 1–100 | 向量召回阶段切片数，直接影响Rerank费用与精度。默认50，降低可节省成本但可能影响效果。 |
|
||||
| | 最大召回数量 | 1–20 | 最终返回给大模型的切片数（经重排+阈值过滤后）。 |
|
||||
| **知识库配置** | 知识库类型 | 文档搜索 / 数据查询 / 图片问答 / 音视频搜索 | 决定解析方式、向量模型及支持的操作（如音视频类不支持新增切片）[知识库配额与限制 (raw/application-user-guide/knowledge-base/rag-knowledge-base-specifications.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-specifications.md)。 |
|
||||
| | 元数据抽取 | 支持常量/变量/大模型/正则/关键词搜索 | 在切片级注入上下文（如`filename`、`date`），用于结构化过滤，**创建后不可修改**。 |
|
||||
| | 标签过滤 | 单文件最多32个标签 | 用于前置筛选文件，提升跨类别检索精度，支持API与控制台调试时指定。 |
|
||||
知识库效果高度依赖关键参数配置，主要分为三类：
|
||||
|
||||
**1. 检索阶段参数**
|
||||
- `初步向量检索 TopK` / `初步关键词检索 TopK`：控制向量与关键词双路召回的初始切片数（取值 1–100，默认 50）。此值直接影响 Rerank 模型的 [Token](../concepts/token.md) 消耗量，是成本优化的关键杠杆 [知识检索 (raw/application-user-guide/knowledge-base/rag-knowledge-retrieval.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-retrieval.md)。
|
||||
- `相似度阈值`：过滤排序后得分低于该值的切片（取值 0.01–1.0）。过高易漏召，过低引入噪声。
|
||||
- `最大召回数量`：最终返回给下游（大模型或前端）的切片总数（取值 1–20）。
|
||||
|
||||
**2. 知识库元数据与标签**
|
||||
- `Meta信息抽取`：支持常量、变量（`file_name`, `cat_name`）、大模型提取、正则、关键词搜索五种方式，为文本切片附加结构化上下文，是解决“多文件同质内容召回不精准”问题的核心手段 [RAG效果优化 (raw/application-user-guide/knowledge-base/rag-optimization.md)](../../raw/application-user-guide/knowledge-base/rag-optimization.md)。
|
||||
- `标签过滤`：在上传或数据管理页为文件打标，检索时可按标签精确限定范围，适用于按业务域（如『硬件』『软件』）隔离知识场景。
|
||||
|
||||
**3. 高级策略参数**
|
||||
- `多轮对话改写`：在创建知识库时启用，可基于历史对话上下文自动补全当前 Query，显著提升多轮会话中指代消解与意图理解的准确性，但创建后不可修改。
|
||||
- `权重`：当应用绑定多个知识库时，可为各库分配权重（数字越大优先级越高），系统在加权重排后优先返回高权重库的切片。**注意**：权重仅在同类型知识库（如均为文档搜索类）间生效，跨类型（如文档搜索 vs 数据查询）无效。
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **控制台快速接入**：
|
||||
1. 在[知识库页面](https://bailian.console.aliyun.com/?tab=app#/knowledge-base)创建标准版/旗舰版知识库，上传文件并配置解析策略（推荐“智能切分”）；
|
||||
2. 在智能体/工作流应用中，通过“文档知识库”节点或“知识库”节点关联知识库，设置权重、TopK及提示词（如`{result}`变量引用检索结果）；
|
||||
3. 对于外部系统，调用[知识库API](https://help.aliyun.com/zh/model-studio/rag-knowledge-base-api-guide)（仅支持文档搜索类）完成创建、上传、检索全流程 [知识库API指南 (raw/application-user-guide/knowledge-base/rag-knowledge-base-api-guide.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-api-guide.md)。
|
||||
|
||||
- **高级能力启用**：
|
||||
- **多轮对话改写**：在知识库创建时开启，自动补全指代与上下文，提升多轮检索准确性；
|
||||
- **知识库路由**：在检索/问答服务中开启，由qwen-plus模型动态选择目标知识库，产生额外模型费用；
|
||||
- **日志监控**：开通SLS日志服务，通过`pipeline_id`（知识库ID）、`latency`、`response_code`等字段进行用量审计与问题排查 [知识库日志与监控 (raw/application-user-guide/knowledge-base/rag-knowledge-base-log-monitoring.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-log-monitoring.md)。
|
||||
知识库可通过三种方式集成到业务中：
|
||||
- **控制台零代码集成**：在[应用管理](https://bailian.console.aliyun.com/#/app-center)中，为智能体或工作流应用添加“文档知识库”节点，选择知识库并配置相似度阈值、权重等参数；或直接使用“知识检索”/“知识问答”独立服务，发布后即可通过 Web UI 或 API 调用。
|
||||
- **工作流节点集成**：在工作流画布中拖入“知识库”节点，配置 `content` 输入（通常为 `query` 变量）、选择固定知识库或动态 `CodeList`，设置 `TopK`，再连接至大模型节点，并在提示词中通过 `{知识库1/result}` 引用检索结果。
|
||||
- **API 集成**：通过百炼 SDK（Python/Java 等）调用知识库 API，实现自动化创建、文件上传、索引提交与检索。完整示例见 [知识库API指南 (raw/application-user-guide/knowledge-base/rag-knowledge-base-api-guide.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-api-guide.md)，需提前完成子账号权限配置、AccessKey 设置及业务空间 ID 获取。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域与权限限制**：
|
||||
- 功能仅限华北2（北京）地域，其他地域不可用；
|
||||
- 子账号需授予`AliyunBailianDataFullAccess`策略并加入业务空间方可调用API [知识库API指南 (raw/application-user-guide/knowledge-base/rag-knowledge-base-api-guide.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-api-guide.md)。
|
||||
|
||||
- **配额与规格**：
|
||||
- 标准版：1 QPS固定并发，100 GB平台存储；旗舰版：1–200 RCU可调（1 RCU ≈ 50 QPS），9,999 GB平台存储；
|
||||
- 单知识库文件无硬性上限（非结构化），但单次控制台上传限50个文件；
|
||||
- 文本切片长度上限6000字符，音视频类知识库不支持新增切片 [知识库配额与限制 (raw/application-user-guide/knowledge-base/rag-knowledge-base-specifications.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-specifications.md)。
|
||||
|
||||
- **计费与成本**：
|
||||
- 规格费用（按小时）+ 模型调用费用（按[Token](../concepts/token.md)）双重计费；
|
||||
- Rerank费用取决于**初步召回总切片数**（非最终返回数），关闭Rerank或调低TopK可显著降本；
|
||||
- 免费额度（720小时）仅抵扣标准版规格费，不覆盖模型调用费用 [知识库计费说明 (raw/application-user-guide/knowledge-base/billing-for-knowledge-base.md)](../../raw/application-user-guide/knowledge-base/billing-for-knowledge-base.md)。
|
||||
|
||||
- **关键注意事项**：
|
||||
> **注意**：知识库类型、元数据抽取配置、多轮对话改写开关均**创建后不可修改**，需谨慎设置；
|
||||
> **注意**：删除知识库将**永久清除数据且无法恢复**，操作前务必确认；
|
||||
> **注意**：使用“视觉理解”场景时，向量模型强制为`qwen3-vl-embedding`且不可更改，需确保文件格式符合多模态解析要求。
|
||||
- **地域限制**：知识库功能**仅限中国站华北2（北京）地域**，新加坡、法兰克福等国际地域不支持，此限制在文档 1 和文档 3 中均被强调为“重要”。
|
||||
- **配额与规格**：标准版知识库上限 1 QPS、100 GB 存储；旗舰版支持 50–10,000 QPS（按 RCU 计费）与 9,999 GB 存储。单次控制台导入文件上限 50 个，单个文件最大 150 MB（PDF/DOCX）或 512 MB（音视频）[知识库配额与限制 (raw/application-user-guide/knowledge-base/rag-knowledge-base-specifications.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-specifications.md)。
|
||||
- **模型费用独立计费**：知识库运行的规格费用（按小时）与模型调用费用（按 [Token](../concepts/token.md)）完全分离。向量化（`text-embedding-v4`）、排序（`qwen3-rerank`）、路由（`qwen-plus`）及问答生成（`qwen3.7-plus`）均产生额外费用，且多知识库场景下费用线性叠加 [知识库计费说明 (raw/application-user-guide/knowledge-base/billing-for-knowledge-base.md)](../../raw/application-user-guide/knowledge-base/billing-for-knowledge-base.md)。
|
||||
- **不可逆操作**：删除知识库将**永久清除所有数据且无法恢复**；知识库类型（如文档搜索、视觉理解）及 `Meta信息抽取` 配置在创建后不可更改；`多轮对话改写` 若创建时未开启，则后续无法补开。
|
||||
- **日志与监控**：所有检索调用默认投递至 SLS 日志服务，字段包含 `request_id`、`pipeline_id`（知识库 ID）、`latency`、`response_code` 及完整的 `response_body.data.nodes[]`（含 `score`、`text`、`metadata`），可用于审计、性能分析与问题排查 [知识库日志与监控 (raw/application-user-guide/knowledge-base/rag-knowledge-base-log-monitoring.md)](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-log-monitoring.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
@@ -66,9 +51,9 @@
|
||||
- [RAG效果优化](../../raw/application-user-guide/knowledge-base/rag-optimization.md)
|
||||
- [知识库API指南](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-api-guide.md)
|
||||
- [知识库日志与监控](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-log-monitoring.md)
|
||||
- [知识检索](../../raw/application-user-guide/knowledge-base/rag-knowledge-retrieval.md)
|
||||
- [知识库计费说明](../../raw/application-user-guide/knowledge-base/billing-for-knowledge-base.md)
|
||||
- [知识库配额与限制](../../raw/application-user-guide/knowledge-base/rag-knowledge-base-specifications.md)
|
||||
- [知识库计费说明](../../raw/application-user-guide/knowledge-base/billing-for-knowledge-base.md)
|
||||
- [知识检索](../../raw/application-user-guide/knowledge-base/rag-knowledge-retrieval.md)
|
||||
- [知识问答](../../raw/application-user-guide/knowledge-base/rag-knowledge-qa.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,53 +1,65 @@
|
||||
# llm application
|
||||
|
||||
`llm application` 是阿里云百炼平台面向大语言模型（LLM）构建的三类核心应用范式之一，专为突破模型原生能力边界而设计。它通过提示词驱动、自主规划与工具协同，将私有知识库、实时数据源、代码执行等外部能力无缝集成到对话流中，适用于开放式意图理解与动态任务求解场景，如智能客服、知识问答、旅行规划等。开发者可零代码配置，亦可通过 API 或高代码方式深度定制。
|
||||
`llm application` 是阿里云百炼平台提供的面向大语言模型（LLM）的三类核心应用构建范式之一，用于突破模型在私有知识访问、实时信息获取、复杂任务规划等方面的原生局限。它通过零代码/低代码方式将 LLM 与知识库、MCP 工具、记忆等能力深度集成，支持从简单问答到多步自主决策的智能任务执行。开发者可根据业务需求，在智能体（Agent）、工作流（Workflow）和高代码应用三种模式中选型，其中智能体应用强调 AI 自主推理与动态工具调度，是处理开放式、意图不确定任务的首选方案 [应用类型介绍](../../raw/application-user-guide/llm-application/application-introduction.md)。
|
||||
|
||||
## 支持的模型/功能
|
||||
## 支持的模型与功能
|
||||
|
||||
- **核心模型要求**：推荐选用具备强工具调用与多步推理能力的模型，如 `千问-Max` 系列；`千问-VL` 系列模型在关闭预解析时仍可直接处理图片/视频，此特性在[新版智能体应用 (raw/application-user-guide/llm-application/new-single-agent-application.md)](../../raw/application-user-guide/llm-application/new-single-agent-application.md)中有明确说明。
|
||||
- **关键能力模块**：
|
||||
- **知识库（RAG）**：作为可调度工具接入新版智能体（Agent 2.0），支持标签过滤以提升检索精度；旧版智能体（Agent 1.0）仅支持静态检索增强 [智能体应用 (raw/application-user-guide/llm-application/single-agent-application.md)](../../raw/application-user-guide/llm-application/single-agent-application.md)。
|
||||
- **MCP 工具**：统一通过 MCP 协议接入，包括官方 MCP 广场服务与自定义 MCP，支持多步、非固定顺序调用；[插件](../concepts/plugin.md)（Plugin）在旧文档中仍被提及，但新版已全面迁移至 MCP 架构 [新版智能体应用 (raw/application-user-guide/llm-application/new-single-agent-application.md)](../../raw/application-user-guide/llm-application/new-single-agent-application.md)。
|
||||
> **注意**：文档3（`single-agent-application.md`）仍使用“[插件](../concepts/plugin.md)”术语并描述其调用逻辑，而文档1（`new-single-agent-application.md`）已明确将所有外部能力统一为 MCP 工具，并强调“[插件](../concepts/plugin.md)也支持一键转换为 MCP 服务”。因此，**新项目应基于 MCP 架构开发，避免依赖旧插件接口**。
|
||||
- **文件处理模式**：支持三种模式——全文引用（适合短文档总结）、切片检索（RAG 风格，适合长文档问答）、自定义处理（模型自主调用工具，如图像风格转换）。不同模式对 [Token](../concepts/token.md) 消耗与适用场景差异显著，详见[文件问答 (raw/application-user-guide/llm-application/file-q-a.md)](../../raw/application-user-guide/llm-application/file-q-a.md)。
|
||||
- **核心模型要求**：推荐选用具备强工具调用与多步规划能力的模型，如 `千问-Max` 系列；`千问-VL` 系列模型因具备[多模态](../concepts/multi-modal.md)能力，可直接解析图片/视频，即使关闭预解析亦能生效 [新版智能体应用 (raw/application-user-guide/llm-application/new-single-agent-application.md)](../../raw/application-user-guide/llm-application/new-single-agent-application.md)。
|
||||
- **[文件处理](../concepts/file-processing.md)模式**：支持三种模式——**全文引用**（适合总结/翻译）、**切片检索（RAG）**（适合长文档精准问答）、**自定义处理**（依赖配置的 MCP 或插件完成图像风格转换、音视频分析等复杂操作）[文件问答](../../raw/application-user-guide/llm-application/file-q-a.md)。
|
||||
- **内置能力**：
|
||||
- **知识库（RAG）**：作为可被智能体自主规划调用的“工具”，支持标签过滤以提升检索精度；检索结果占用输入 [Token](../concepts/token.md)，需注意上下文窗口限制 [新版智能体应用 (raw/application-user-guide/llm-application/new-single-agent-application.md)](../../raw/application-user-guide/llm-application/new-single-agent-application.md)。
|
||||
- **MCP 工具**：所有外部服务（含官方 MCP 广场及自定义服务）均以 MCP 协议接入，支持非固定顺序、多轮动态调用。
|
||||
- **内置沙箱工具**：`bash`、`write`、`read`、`edit`、`glob`、`grep`、`download_file`，全部默认关闭，按需启用。
|
||||
- **技能（Skill）**：可复用的能力包，自动识别任务并触发对应逻辑，无需编码。
|
||||
- **记忆**：仅支持短期记忆（0–30 轮上下文），[长期记忆](../concepts/long-term-memory.md)暂未上线。
|
||||
|
||||
> **注意**：文档 3（`single-agent-application.md`）仍提及“插件”概念，而文档 1（`new-single-agent-application.md`）已明确统一为“MCP 协议接入”。当前平台已全面迁移至 MCP 架构，旧版插件接口已不推荐使用，应优先通过 MCP 集成外部能力。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **`enable_thinking`**：控制是否开启思考模式，仅对支持该能力的模型生效；开启后可在运行中展示“规划-执行-反思”链路，用于调试决策路径。
|
||||
- **`ReAct 最大轮次`**：取值范围 1–50，限制单次会话中工具调用总次数；超限后自动终止调用并生成最终回复。
|
||||
- **文件处理参数**：
|
||||
- 全文引用模式：`单文件最大解析长度（token）`（截断位置为文件末尾）、`最大拼装长度（token）`（截断位置为最后拼接文件末尾）。
|
||||
- 切片检索模式：`召回片段数`、`最大拼装长度`（按相关性得分丢弃低分片段）。
|
||||
- **记忆配置**：短期记忆支持 0–30 轮上下文；[长期记忆](../concepts/long-term-memory.md)当前为计划中功能，暂未开放。
|
||||
| 参数 | 说明 | 取值范围/示例 | 备注 |
|
||||
|------|------|----------------|------|
|
||||
| `enable_thinking` | 是否开启模型思考模式（用于展示推理链路） | `true` / `false` | 仅对支持该能力的模型（如 `千问-Max`）生效；不支持时参数不可见 [新版智能体应用 (raw/application-user-guide/llm-application/new-single-agent-application.md)](../../raw/application-user-guide/llm-application/new-single-agent-application.md) |
|
||||
| `ReAct 最大轮次` | 单次会话中工具调用的最大次数 | 1–50 | 超限后强制终止工具链并生成最终回复 |
|
||||
| `最长回复长度` | 模型生成内容的 token 上限（不含提示词） | 正整数 | 影响输出完整性，需结合模型上下文窗口设置 |
|
||||
| `温度系数（temperature）` | 控制输出随机性与多样性 | 0.0–2.0 | 值越高越随机，建议问答场景设为 0.1–0.6 |
|
||||
| `单文件最大解析长度（token）` | 全文引用模式下单个文件提取上限 | 正整数 | 超出部分从文件末尾截断 |
|
||||
| `召回片段数` | 切片检索模式下返回的相关文本片段数量 | 正整数 | 影响答案覆盖广度与精度平衡 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **创建与配置**：在百炼控制台「应用管理」→「创建应用」→ 选择「智能体应用」→ **优先选用 Agent 2.0（新版）**；配置模型、系统提示词（支持自定义变量）、知识库、MCP 工具及文件处理策略。
|
||||
- **交互方式**：
|
||||
- 文本对话：支持多轮会话，输入文本或上传文件（单次最多 10 个，单文件 ≤10MB）。
|
||||
- 文件问答：依据所选模式（全文引用/切片检索/自定义处理）自动触发对应处理逻辑。
|
||||
- **发布与调用**：
|
||||
- 应用必须**发布后**方可调用；
|
||||
- API 调用需通过「发布渠道」→「API 调用」获取 endpoint 与鉴权方式；
|
||||
- 高代码应用可进一步封装为 Serverless Function 或 K8s 服务，并通过 API 网关暴露生产级接口。
|
||||
1. **创建与配置**：
|
||||
- 访问控制台 [应用管理](https://bailian.console.aliyun.com/?tab=app#/app-center)，选择 **智能体应用 > Agent 2.0** 创建；
|
||||
- 在模型选择器中选定模型（如 `千问-Plus-Latest`），并通过参数配置器调整 `temperature`、`enable_thinking` 等；
|
||||
- 配置系统提示词（支持嵌入自定义变量 `/var_name`），并按需开启知识库、MCP、内置工具等能力。
|
||||
|
||||
2. **文件交互**：
|
||||
- 在调试窗口上传文件后，根据所选处理模式（全文引用/切片检索/自定义处理）进行对话；
|
||||
- 若启用自定义处理，需提前挂载对应 MCP（如人物重绘）或插件，并确保模型能理解调用意图。
|
||||
|
||||
3. **发布与调用**：
|
||||
- **必须先发布**应用，才能通过 API 或第三方渠道调用；
|
||||
- 发布后，在 **发布渠道 > API 调用** 中获取 endpoint 与鉴权方式；
|
||||
- API 调用时，文件需通过 `file_list`（通用文件 URL）、`image_list`（图片 URL）或 `session_file_id`（上传 API 返回 ID）传递，**无法在请求中动态切换[文件处理](../concepts/file-processing.md)模式** [文件问答](../../raw/application-user-guide/llm-application/file-q-a.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **版本不兼容**：Agent 1.0 与 Agent 2.0 基于不同技术架构，**不支持升级、降级或互转**；如需迁移，须重新创建新版应用 [新版智能体应用 (raw/application-user-guide/llm-application/new-single-agent-application.md)](../../raw/application-user-guide/llm-application/new-single-agent-application.md)。
|
||||
- **文件有效期**：聊天窗口上传的文件**仅在当前会话有效**，刷新或关闭页面即失效；生产环境推荐使用文件上传 API 获取 `session_file_id`（有效期通常 24 小时）。
|
||||
- **计费要点**：
|
||||
- 模型调用费用取决于输入/输出 [Token](../concepts/token.md) 数量，其中知识库召回内容、文件解析文本均计入输入 [Token](../concepts/token.md)；
|
||||
- 全文引用模式 Token 消耗显著高于切片检索模式，长文档场景务必优先评估 RAG 策略；
|
||||
- MCP 工具调用可能产生额外费用（如第三方 API 调用），由服务提供方收取，百炼平台不加收。
|
||||
- **隐式缓存支持**：智能体自动启用上下文前缀缓存（如系统提示词、知识库内容），命中部分 Token 按标准单价 20% 计费；但**暂不支持显式缓存配置**。
|
||||
- **版本兼容性**：Agent 1.0 与 Agent 2.0 架构不兼容，**不支持升级或降级**，需重新创建应用 [新版智能体应用 (raw/application-user-guide/llm-application/new-single-agent-application.md)](../../raw/application-user-guide/llm-application/new-single-agent-application.md)。
|
||||
- **文件时效性**：聊天窗口上传的文件**仅在当前会话有效**，刷新或关闭页面即失效；生产环境强烈推荐使用 `session_file_id` 方式上传 [文件问答](../../raw/application-user-guide/llm-application/file-q-a.md)。
|
||||
- **计费要点**：
|
||||
- 模型调用费用 = 输入 [Token](../concepts/token.md)（含知识库召回内容、文件解析文本） + 输出 [Token](../concepts/token.md)；
|
||||
- 全文引用模式 Token 消耗显著高于切片检索；
|
||||
- MCP 工具调用可能产生第三方费用，百炼平台不代收。
|
||||
- **缓存机制**：仅支持**隐式缓存**（自动识别公共前缀并按 20% 计费），暂不支持显式缓存配置 [新版智能体应用 (raw/application-user-guide/llm-application/new-single-agent-application.md)](../../raw/application-user-guide/llm-application/new-single-agent-application.md)。
|
||||
- **超时限制**：自定义 MCP 服务调用超时为 **5 秒**，需确保服务响应在此时限内 [智能体应用 (raw/application-user-guide/llm-application/single-agent-application.md)](../../raw/application-user-guide/llm-application/single-agent-application.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [新版智能体应用](../../raw/application-user-guide/llm-application/new-single-agent-application.md)
|
||||
- [应用类型介绍](../../raw/application-user-guide/llm-application/application-introduction.md)
|
||||
- [智能体应用](../../raw/application-user-guide/llm-application/single-agent-application.md)
|
||||
- [高代码应用](../../raw/application-user-guide/llm-application/rich-code-application.md)
|
||||
- [工作流应用](../../raw/application-user-guide/llm-application/workflow-application.md)
|
||||
- [高代码应用](../../raw/application-user-guide/llm-application/rich-code-application.md)
|
||||
- [文件问答](../../raw/application-user-guide/llm-application/file-q-a.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,48 +1,49 @@
|
||||
# managed agents
|
||||
|
||||
Managed Agents 是百炼平台提供的智能体托管运行时，专为多步工具调用、代码执行、文件处理等长时运行任务设计。平台统一托管会话状态、沙箱环境与工具执行生命周期，智能体在隔离的云端容器中自主执行命令、读写文件、安装依赖，并通过服务端持久化的事件流反馈全过程。相比无状态的智能体应用，Managed Agents 提供有状态会话、中断续接与沙箱级资源隔离能力。
|
||||
Managed Agents 是百炼平台提供的智能体托管运行时，专为多步工具调用、代码执行、[文件处理](../concepts/file-processing.md)等长时运行任务设计。平台统一托管会话状态、沙箱环境与工具执行生命周期，智能体在隔离的云端容器中自主运行命令、读写文件、安装依赖，并通过持久化的事件流反馈全过程。开发者只需关注 Agent 逻辑与任务编排，无需自行实现代理循环、沙箱编排或工具调度基础设施。
|
||||
|
||||
## 支持的模型与功能
|
||||
|
||||
- **支持模型**：当前支持 `qwen3-max`、`qwen3.7-plus` 等 Qwen 系列大模型（详见 [概述](../../raw/application-user-guide/managed-agents/managed-agents-introduction.md)）；模型需在创建 Agent 时显式指定，不支持运行时动态切换。
|
||||
- **内置工具**：默认提供 `bash`（命令执行）、`read`/`write`/`edit`（文件操作）、`glob`/`grep`（文件搜索）、`download_file`（URL 下载）共 7 个 builtin_toolkit 工具；所有工具均在沙箱内受限执行，无 root 权限。
|
||||
- **扩展能力**：
|
||||
- 可挂载预置 Skill 封装端到端流程；
|
||||
- 支持接入 MCP 服务调用外部 API；
|
||||
- 支持挂载上传文件或远程 URL 资源（单文件 ≤10 MB），挂载路径固定为 `/mnt/session/uploads/...`（详见 [Agent 上下文管理](../../raw/application-user-guide/managed-agents/managed-agents-context.md)）。
|
||||
- **模型支持**：当前支持 `qwen3-max`、`qwen3.7-plus` 等 Qwen 系列大模型（详见 [快速开始](../../raw/application-user-guide/managed-agents/managed-agents-quick-start.md)）；模型 ID 需严格匹配平台已发布版本，不支持自定义模型镜像。
|
||||
- **核心功能**：
|
||||
- 工具调用：内置 `bash`、`read`、`write`、`edit`、`glob`、`grep`、`download_file` 7 类工具，默认全启用；
|
||||
- MCP 服务接入：可挂载外部工具服务（[构建 Agent](../../raw/application-user-guide/managed-agents/managed-agents-agent.md) 中说明其为可选配置）；
|
||||
- Skill 封装：支持预置技能组合，用于端到端流程抽象；
|
||||
- [文件处理](../concepts/file-processing.md)：支持上传挂载（单文件 ≤10 MB）、URL 下载、沙箱内读写编辑（[Agent 上下文管理](../../raw/application-user-guide/managed-agents/managed-agents-context.md) 明确路径约定为 `/mnt/session/uploads/...`）。
|
||||
|
||||
> **注意**：文档 2 中示例使用 `qwen3-max`，而文档 1 的表格示例为 `qwen3.7-plus`；实际可用模型以控制台下拉列表或 [API 文档](https://help.aliyun.com/zh/model-studio/agent-create) 为准，旧模型名可能已下线。
|
||||
> **注意**：文档 2 中称“支持命令执行、文件操作、MCP 服务、Skill”，而文档 3 和文档 4 均未明确列出具体工具集；实际可用工具以 [快速开始](../../raw/application-user-guide/managed-agents/managed-agents-quick-start.md) 中列出的 7 个内置工具为准，该文档为最新且具操作性，应作为权威参考。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 说明 | 必填 | 示例 |
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `agent.id` | 智能体唯一标识，创建后复用 | 是 | `"agent_xxx"` |
|
||||
| `environment_id` | 运行环境 ID，决定沙箱配置 | 是 | `"env_xxx"` |
|
||||
| `tools` | 工具列表，仅支持 `{"type": "builtin_toolkit"}` 或显式工具数组 | 是（至少一项） | `[{"type": "builtin_toolkit"}]` |
|
||||
| `resources` | 挂载资源列表（含 `resource_id` 和 `mount_path`） | 否 | `[{"resource_id": "res_abc", "mount_path": "/mnt/session/uploads/data.csv"}]` |
|
||||
| `networking.type` | 环境网络策略，仅支持 `"unrestricted"` 或 `"restricted"`（默认） | 否 | `"unrestricted"` |
|
||||
| `model.id` | string | 是 | 模型 ID，如 `"qwen3-max"`；不支持别名或版本通配符 |
|
||||
| `system` / `system_prompt` | string | 是 | 系统提示词，定义角色与行为边界；控制台预填通用模板，API 创建时需显式传入 |
|
||||
| `tools` | array | 否（默认全启用） | 工具配置数组，最小粒度为 `{"type": "builtin_toolkit"}`；暂不支持按单个工具启停（如仅启用 `bash` 而禁用 `grep`） |
|
||||
| `environment_id` | string | 是（创建 Session 时） | 运行环境 ID，指向独立托管的沙箱容器（[配置 Agent 环境](../../raw/application-user-guide/managed-agents/managed-agents-environment.md) 强调其复用性） |
|
||||
| `resources` | array | 否 | 挂载资源列表，含 `resource_id` 与 `mount_path`；挂载后路径固定为 `/mnt/session/uploads/...` |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **创建智能体**：调用 `POST /api/v1/agentstudio/agents`，指定 `name`、`model.id`、`system` 和 `tools`（参考 [快速开始](../../raw/application-user-guide/managed-agents/managed-agents-quick-start.md) 中的 API 示例）。
|
||||
2. **创建环境**：调用 `POST /api/v1/agentstudio/environments`，配置 `config.type="cloud"` 及 `packages`（如 `pip: ["pandas"]`）、`networking`。
|
||||
3. **创建会话**：调用 `POST /api/v1/agentstudio/sessions`，绑定 `agent` 和 `environment_id`，可选传入 `resources`。
|
||||
4. **发送事件**：向 `POST /api/v1/agentstudio/sessions/{session_id}/events` 提交用户消息（`role: "user"`），内容为标准 Message 格式。
|
||||
5. **接收事件流**：通过 SSE 订阅 `GET /api/v1/agentstudio/sessions/{session_id}/events/stream`，监听 `message`、`tool_output`、`session_status` 等事件类型。
|
||||
1. **创建智能体**：通过控制台向导或 API 指定名称、模型、系统提示词和工具（[快速开始](../../raw/application-user-guide/managed-agents/managed-agents-quick-start.md) 提供完整示例）；
|
||||
2. **创建环境**：配置云端沙箱类型、预装包（`apt`/`pip`）、网络策略（`unrestricted` 或 `restricted`）；
|
||||
3. **创建会话**：绑定智能体 ID 与环境 ID，可同时指定 `resources` 挂载文件；
|
||||
4. **发送事件**：使用 `POST /sessions/{id}/events` 提交用户消息（`role: "user"`），内容支持[多模态](../concepts/multi-modal.md)块（text、file_ref 等）；
|
||||
5. **接收响应**：通过 SSE 流订阅 `/sessions/{id}/events/stream`，监听 `message`、`tool_call`、`tool_output`、`session_status` 等事件类型。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **沙箱约束**：所有命令在无特权 Linux 容器中执行，禁止访问宿主机、修改系统时间、使用 `sudo` 或启动后台守护进程。
|
||||
- **资源隔离**：同一资源挂载到多个会话时，各会话获得独立副本；会话终止后副本自动清理，原始资源不受影响（详见 [Agent 上下文管理](../../raw/application-user-guide/managed-agents/managed-agents-context.md)）。
|
||||
- **超时机制**：SSE 流默认超时 120 秒，需客户端主动重连；会话空闲 30 分钟自动进入 `idle` 状态，可手动唤醒或终止。
|
||||
- **文件大小限制**：上传文件单个 ≤10 MB；沙箱内临时文件总容量受环境配额限制，超出将触发 `tool_error` 事件。
|
||||
- **状态持久化**：事件历史在服务端完整保留，但会话 `status` 仅反映当前运行态（`running`/`idle`/`terminated`），不自动保存中间文件系统快照。
|
||||
- **会话生命周期**：单次会话最长运行 2 小时，超时自动终止；可通过 `session_status` 事件监听 `idle` 或 `terminated` 状态；
|
||||
- **文件限制**：上传挂载文件单个 ≤10 MB，总挂载容量无明确上限但受工作空间配额约束；
|
||||
- **环境复用**：一个 Environment 可被多个 Session 复用，但同一 Session 仅能绑定一个 Environment；
|
||||
- **工具执行隔离**：所有工具调用均在沙箱内执行，`bash` 命令无法访问宿主机，`write`/`edit` 仅作用于 `/mnt/session/` 下路径；
|
||||
- **上下文持久化**：会话内文件系统状态跨事件保持，但 Session 终止后沙箱销毁，副本不保留；
|
||||
- **权限要求**：调用方账号需在目标工作空间具备 `AgentStudioFullAccess` 或等效细粒度权限（[快速开始](../../raw/application-user-guide/managed-agents/managed-agents-quick-start.md) 明确前置权限条件）。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [概述](../../raw/application-user-guide/managed-agents/managed-agents-introduction.md)
|
||||
- [快速开始](../../raw/application-user-guide/managed-agents/managed-agents-quick-start.md)
|
||||
- [概述](../../raw/application-user-guide/managed-agents/managed-agents-introduction.md)
|
||||
- [构建 Agent](../../raw/application-user-guide/managed-agents/managed-agents-agent.md)
|
||||
- [配置 Agent 环境](../../raw/application-user-guide/managed-agents/managed-agents-environment.md)
|
||||
- [委派任务给 Agent](../../raw/application-user-guide/managed-agents/managed-agents-session.md)
|
||||
|
||||
@@ -1,44 +1,46 @@
|
||||
# memory library overview
|
||||
|
||||
记忆库是百炼平台提供的[长期记忆](../concepts/long-term-memory.md)能力核心组件，用于突破大模型上下文窗口限制，实现跨会话、跨轮次的用户偏好与历史信息持久化。它通过自动从对话中提取关键事件（记忆片段）或结构化属性（用户画像），并基于语义检索在后续交互中动态召回，使智能体具备持续性理解能力。该能力以开放 API 形式提供，支持直接集成、OpenClaw [插件](../concepts/plugin.md)接入及控制台管理。
|
||||
记忆库是百炼平台提供的[长期记忆](../concepts/long-term-memory.md)能力核心组件，用于突破大模型上下文窗口限制，实现跨会话、跨对话的用户偏好与关键信息持久化。它通过自动提取对话中的记忆片段和结构化用户画像，并基于语义检索在后续交互中动态召回，使智能体具备持续理解能力。该能力以开放 API 形式提供，支持直接集成或通过插件（如 OpenClaw）自动接入。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **记忆片段**：从对话消息（`messages`）中自动提炼关键事件（如“每天上午9点提醒我喝水”），支持自定义内容写入（`custom_content`）、元数据标注（`meta_data`）及自动去重更新。适用于大多数[长期记忆](../concepts/long-term-memory.md)场景。
|
||||
- **用户画像**：基于预定义的画像模板（`profile_schema`），从对话中抽取结构化属性（如年龄、职业、爱好）。需先调用 `CreateProfileSchema` 创建模板，再在 `AddMemory` 中指定 `profile_schema` 参数触发抽取。详见 [长期记忆 API](../../raw/application-user-guide/memory-library-overview/long-term-memory-2-0.md)。
|
||||
- **自动捕获与召回**：OpenClaw [插件](../concepts/plugin.md)支持 `autoCapture`（对话结束自动写入）和 `autoRecall`（对话开始前自动检索注入）机制，无需手动调用，显著降低集成门槛。参见 [为 OpenClaw 配置长期记忆插件](../../raw/application-user-guide/memory-library-overview/modelstudio-memory-for-openclaw.md)。
|
||||
- **记忆片段（Memory Snippet）**：从对话消息中自动提炼关键事件（如“每天上午9点提醒我喝水”），支持自定义内容写入、语义检索、去重更新与元数据分类管理。适用于大多数[长期记忆](../concepts/long-term-memory.md)场景。
|
||||
- **用户画像（User Profile）**：基于预定义 Schema 从对话中抽取结构化属性（如年龄、职业、爱好），支持多轮渐进式填充与完整画像获取。适用于需固定字段的业务场景。
|
||||
- **双模态接入**：既可通过 [AddMemory](https://help.aliyun.com/zh/model-studio/long-term-memory-api-reference) 等原生 API 手动控制，也支持通过 [为 OpenClaw 配置长期记忆插件](../../raw/application-user-guide/memory-library-overview/modelstudio-memory-for-openclaw.md) 实现全自动捕获（`autoCapture`）与召回（`autoRecall`）。
|
||||
- **多应用共享**：同一记忆库可被多个应用或 Agent 共享，通过 `user_id` 隔离数据空间，无需额外配置即可复用。
|
||||
|
||||
> **注意**：文档 1 称记忆片段默认有效期为 180 天，而文档 3 明确说明“生成的记忆片段与用户画像暂无失效日期”。该矛盾以文档 3 为准——**当前版本记忆无强制过期机制，过期时间由记忆规则配置决定，未配置时即永不过期**。
|
||||
> **注意**：文档 1 称“默认记忆库已预置一条‘默认项目’记忆片段规则，默认有效期 180 天”，而文档 3 明确指出“生成的记忆片段与用户画像暂无失效日期”。该矛盾源于规则配置项（过期时间）与实际存储行为的差异——规则中设置的“记忆过期时间”仅影响该规则下新写入记忆的生命周期策略，但底层存储本身不强制删除；实际过期由规则调度器执行，非即时物理删除。建议以 [长期记忆 API](../../raw/application-user-guide/memory-library-overview/long-term-memory-2-0.md) 中“暂无失效日期”的表述为准，并在业务侧自行管理清理逻辑。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `user_id` | string | 是 | 用户唯一标识，用于隔离不同用户的记忆空间；同一 `user_id` 下所有记忆共享命名空间。 |
|
||||
| `memory_library_id` | string | 否 | 指定目标记忆库 ID；不填则使用默认记忆库（每个账号自带一个，不可删除）。 |
|
||||
| `project_id` | string | 否 | 记忆片段规则 ID；不填则使用所选记忆库的默认规则。 |
|
||||
| `profile_schema` | string | 否 | 用户画像模板 ID；仅当需触发画像抽取时必填。 |
|
||||
| `top_k` | number | 否（默认 5） | `SearchMemory` 返回的最大记忆条数；推荐值 3–10，平衡效果与性能。 |
|
||||
| `min_score` / `similarity_threshold` | number | 否（默认 0 / 0.5） | 检索相似度阈值（0.0–1.0），低于此值的结果被过滤；文档 1 建议设为 0.5–0.7，文档 2 默认值为 0（即不限制），实际应按业务精度要求调整。 |
|
||||
| 参数 | 类型 | 必填 | 说明 | 来源 |
|
||||
|------|------|------|------|------|
|
||||
| `user_id` | string | 是 | 用户唯一标识，用于隔离记忆空间；不同 `user_id` 数据完全隔离 | [为 OpenClaw 配置长期记忆插件](../../raw/application-user-guide/memory-library-overview/modelstudio-memory-for-openclaw.md) |
|
||||
| `memory_library_id` | string | 否 | 指定记忆库 ID；不填则使用默认记忆库 | [长期记忆 API](../../raw/application-user-guide/memory-library-overview/long-term-memory-2-0.md) |
|
||||
| `project_id` | string | 否 | 记忆片段规则 ID；不填则使用默认规则 | [长期记忆 API](../../raw/application-user-guide/memory-library-overview/long-term-memory-2-0.md) |
|
||||
| `profile_schema` | string | 否 | 用户画像 Schema ID；用于触发结构化属性抽取 | [记忆库](../../raw/application-user-guide/memory-library-overview/memory-library.md) |
|
||||
| `meta_data` | object | 否 | 自定义键值对，用于分类、标记或业务上下文关联 | [长期记忆 API](../../raw/application-user-guide/memory-library-overview/long-term-memory-2-0.md) |
|
||||
| `top_k` | number | 否（默认 5） | 检索返回的最大记忆条数；推荐设为 3–10 平衡效果与性能 | [长期记忆 API](../../raw/application-user-guide/memory-library-overview/long-term-memory-2-0.md) |
|
||||
| `min_score` / `similarity_threshold` | number (0.0–1.0) | 否（默认 0） | 相似度阈值；建议设为 0.5–0.7 避免漏召或噪声 | [记忆库](../../raw/application-user-guide/memory-library-overview/memory-library.md) |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **准备环境**：设置 `DASHSCOPE_API_KEY` 环境变量（获取方式见 [获取 API Key](https://help.aliyun.com/zh/model-studio/get-api-key)）。
|
||||
2. **写入记忆**：调用 `AddMemory` 接口。支持两种模式：
|
||||
- 对话提炼：传入 `messages` 数组，由服务端自动提取（推荐）；
|
||||
- 直接写入：传入 `custom_content` 字符串，绕过提取逻辑（适用于明确已知需存储的内容）。
|
||||
示例见 [记忆库](../../raw/application-user-guide/memory-library-overview/memory-library.md)。
|
||||
3. **检索记忆**：调用 `SearchMemory`（或 `memory_nodes/search`），传入自然语言查询（`query` 或 `messages`）及 `user_id`。OpenClaw [插件](../concepts/plugin.md)还提供 `memory_search` 工具供 Agent 动态调用。
|
||||
4. **管理记忆**：支持 `ListMemory`（分页查看）、`UpdateMemory`（PATCH 更新内容）、`DeleteMemory`（DELETE 删除）等操作，详见 [长期记忆 API](../../raw/application-user-guide/memory-library-overview/long-term-memory-2-0.md)。
|
||||
5. **用户画像工作流**：创建模板（`CreateProfileSchema`）→ 写入带模板 ID 的对话（`AddMemory`）→ 异步获取结果（`GetUserProfile`），完整流程见 [记忆库](../../raw/application-user-guide/memory-library-overview/memory-library.md)。
|
||||
1. **准备凭证**：获取 DashScope API Key 并配置环境变量 `DASHSCOPE_API_KEY`（参见[获取 API Key](https://help.aliyun.com/zh/model-studio/get-api-key)）。
|
||||
2. **写入记忆**：调用 `AddMemory` 接口，传入 `messages`（对话历史）或 `custom_content`（直接内容），指定 `user_id` 及可选参数（如 `memory_library_id`, `profile_schema`）。
|
||||
3. **检索记忆**：调用 `SearchMemory` 接口，传入 `user_id` 和自然语言查询（`query` 或 `messages`），可指定 `top_k` 和 `similarity_threshold`。
|
||||
4. **管理记忆**：使用 `ListMemory` 分页查看、`UpdateMemory` 修改内容、`DeleteMemory` 删除条目（详见 [长期记忆 API](../../raw/application-user-guide/memory-library-overview/long-term-memory-2-0.md)）。
|
||||
5. **用户画像流程**：先调用 `CreateProfileSchema` 定义字段，再在 `AddMemory` 中传入 `profile_schema` ID 触发抽取，最后用 `GetUserProfile` 获取结果。
|
||||
|
||||
> **注意**：OpenClaw 插件封装了上述流程，启用 `autoCapture`/`autoRecall` 后无需手动调用 API；其注册的 `memory_search`、`memory_store` 等工具亦可被 Agent 在运行时主动调用，详见 [为 OpenClaw 配置长期记忆插件](../../raw/application-user-guide/memory-library-overview/modelstudio-memory-for-openclaw.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **配额限制**：阿里云账号级别总调用量 ≤ 3000 QPM；其中 `AddMemory` ≤ 120 QPM，`SearchMemory` ≤ 300 QPM。超出将返回限流错误（HTTP 429）。
|
||||
- **延迟特性**：`AddMemory` 端到端延迟约 500–1000ms，`SearchMemory` 约 200–500ms；OpenClaw 的 `autoCapture` 为异步执行，不影响主响应流。
|
||||
- **插件约束**：OpenClaw 记忆插件为全局配置，所有 Agent 共享同一记忆空间，**暂不支持按 Agent 实例独立隔离记忆**（见 [为 OpenClaw 配置长期记忆插件](../../raw/application-user-guide/memory-library-overview/modelstudio-memory-for-openclaw.md)）。
|
||||
- **字段命名规范**：用户画像中，同一模板内属性名称（`name`）应语义唯一（如避免同时存在“年龄”“年纪”），否则影响抽取准确率（见 [长期记忆 API](../../raw/application-user-guide/memory-library-overview/long-term-memory-2-0.md)）。
|
||||
- **调试建议**：控制台“记忆检索”标签页支持开启“改写”“排序”“意图判别召回”等功能优化效果；生产环境建议开启“排序”并设置 `similarity_threshold` 在 0.5–0.7 区间。
|
||||
- **配额限制**：阿里云账号级别总计不超过 3000 QPM；其中 `AddMemory` ≤ 120 QPM，`SearchMemory` ≤ 300 QPM（参见 [为 OpenClaw 配置长期记忆插件](../../raw/application-user-guide/memory-library-overview/modelstudio-memory-for-openclaw.md)）。
|
||||
- **延迟特性**：`SearchMemory` 端到端延迟约 200–500ms，`AddMemory` 约 500–1000ms；自动捕获为异步执行，不影响主流程响应速度。
|
||||
- **ID 隔离原则**：所有操作必须指定 `user_id`，否则请求将失败；同一 `user_id` 下数据全局可见，不同 `user_id` 间完全隔离。
|
||||
- **默认记忆库约束**：默认记忆库不可删除，但可编辑名称、描述及规则；预置的“默认项目”规则不可删除，仅可编辑（参见 [记忆库](../../raw/application-user-guide/memory-library-overview/memory-library.md)）。
|
||||
- **API Key 要求**：仅支持百炼标准 API Key，不支持 Coding Plan 的 Key（参见 [为 OpenClaw 配置长期记忆插件](../../raw/application-user-guide/memory-library-overview/modelstudio-memory-for-openclaw.md)）。
|
||||
- **画像抽取提示**：画像字段名应语义唯一（避免“姓名”/“名字”并存），且描述需具体；单次对话可能无法提取全部字段，建议多轮渐进收集。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,43 +1,43 @@
|
||||
# model compression
|
||||
|
||||
模型压缩是百炼平台提供的量化能力，通过降低模型参数精度（如 FP16 → INT4/INT8），在保持推理能力基本不变的前提下显著减少部署所需的 MU 规格与成本。该功能仅作用于百炼平台微调产出的自定义模型，属于模型生产链路中可选但关键的一环：[模型调优](https://help.aliyun.com/zh/model-studio/fine-tuning/#73749f1ee5634) → 模型压缩 → [模型部署](https://help.aliyun.com/zh/model-studio/model-deployment-1/#3bc53b23c7shc)。**压缩不可逆**，压缩后模型不支持继续微调或二次压缩。
|
||||
模型压缩是百炼平台提供的量化能力，用于将全精度微调模型转换为低精度版本，在保持可用推理能力的前提下显著降低部署所需的 MU 规格与成本。该功能仅作用于通过百炼完成的微调模型，不支持结构剪枝或知识蒸馏等其他压缩范式。压缩操作不可逆，且压缩后的模型不可继续微调或二次压缩。
|
||||
|
||||
## 支持的模型与功能
|
||||
|
||||
- **支持范围**：仅限通过百炼平台完成微调训练的自定义模型（即“微调产出模型”），不支持基础模型（如 `qwen3.5-flash-2026-02-23` 原始版本）或第三方导入模型。
|
||||
- **技术范畴**：当前仅支持**量化（Quantization）**，不包含结构剪枝、知识蒸馏等其他压缩技术。详见 [原文标题](../../raw/model-user-guide/model-compression/model-compression-introduction.md) 中“功能概述”章节说明。
|
||||
- **地域限制**：仅华北2（北京）地域可用。
|
||||
- **典型收益**：以 `qwen3.5-flash-2026-02-23` 微调模型为例，压缩前部署需 MU1\*2（¥108/小时），压缩后可降至 MU8\*1（¥47/小时），成本节省约 56%。
|
||||
- **支持范围**：仅限百炼平台微调产出的自定义模型（如 `qwen3.5-flash-2026-02-23`），不支持基础模型、第三方模型或 OSS 直接加载模型。具体支持列表以控制台实时展示为准，详见 [模型压缩](../../raw/model-user-guide/model-compression/model-compression-introduction.md)。
|
||||
- **功能边界**：当前仅提供量化（Quantization）一种压缩方式，明确区别于剪枝、蒸馏等技术；完整链路为「模型调优 → 模型压缩 → 模型部署」，各环节不可跳过或逆序，参见 [模型压缩](../../raw/model-user-guide/model-compression/model-compression-introduction.md) 中的功能概述部分。
|
||||
- **地域限制**：仅华北2（北京）地域可用。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 是否必填 | 说明 |
|
||||
|------|----------|------|
|
||||
| **任务名称** | 是 | ≤50 字符；建议含模型简称、量化方式、版本号（如 `qwen35-ft-int4-v1`） |
|
||||
| **选择源模型** | 是 | 仅展示当前工作空间内已完成且状态为“成功”的微调模型；切换源模型将自动清空已选量化模板 |
|
||||
| **量化产出模型名后缀** | 是 | 仅小写字母+数字，≤8 位；将拼接至源模型名后（如源模型 `my-qwen-ft` + 后缀 `int4` → 输出模型 `my-qwen-ft-int4`） |
|
||||
| **量化模板** | 是 | 卡片式选择；模板名中 MU 编号越大，部署规格越小、成本越低，但潜在精度损失可能越高；须先选定源模型才可加载对应模板列表 |
|
||||
| **校准数据** | 条件选填 | 仅当所选模板支持校准时显示；最多选 5 个已发布数据集（不支持 OSS 挂载）；推荐选用与目标推理场景语义一致的数据（如客服场景用对话数据集） |
|
||||
| **任务名称** | 是 | ≤50 字符，建议含模型简称、量化方式与版本号，便于追踪。 |
|
||||
| **选择源模型** | 是 | 仅显示已成功微调的自定义模型；切换源模型会自动清空已选量化模板。 |
|
||||
| **量化产出模型名后缀** | 是 | 仅小写字母+数字，≤8 位，将拼接至源模型名后形成新模型标识（如 `my-model-quant8`）。 |
|
||||
| **量化模板** | 是 | 卡片式选择，模板名中 MU 编号越大，部署规格越小、成本越低，但潜在精度损失可能增加；须先选定源模型才可加载对应模板列表。 |
|
||||
| **校准数据** | 条件必填 | 仅当所选模板需校准输入时出现；最多选 5 个已发布数据集（不支持 OSS 挂载），推荐语义贴近目标推理场景的数据，详见 [模型压缩](../../raw/model-user-guide/model-compression/model-compression-introduction.md) 的校准数据说明。 |
|
||||
|
||||
> **注意**：量化模板的选择直接影响部署规格与精度表现，不同模型支持的模板集合不同，实际可用项以控制台实时加载为准。请参考 [原文标题](../../raw/model-user-guide/model-compression/model-compression-introduction.md) 中“创建压缩任务”章节的配置说明。
|
||||
> **注意**：文档中“压缩前部署规格 MU1\*2（¥108/小时）→ 压缩后 MU8\*1（¥47/小时）”为示例值，实际规格与价格请以控制台创建时实时显示为准；不同模型系列的量化收益存在差异，不可直接套用。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **前提条件**：确保工作空间中已存在状态为“成功”的微调模型（参见 [原文标题](../../raw/model-user-guide/model-compression/model-compression-introduction.md) “前提条件”部分）。
|
||||
2. **入口路径**：控制台 → **模型** > **模型训练** > **模型压缩** → **创建压缩任务**。
|
||||
3. **配置并提交**：填写必填参数，确认量化模板与校准数据（如需），单击**开始压缩**（按钮仅在全部必填项合法时启用）。
|
||||
4. **监控进度**：在任务列表页点击任务名称进入详情页，通过**详情**页签查看状态与配置，通过**日志**页签实时跟踪执行过程（支持按级别着色、下载全量日志、自动刷新等）。
|
||||
5. **结果验证**：任务状态变为 `SUCCEEDED` 后，压缩后模型将出现在模型中心，可直接用于部署；建议使用业务测试集进行推理效果验证。
|
||||
1. **前提条件**：确保工作空间中已存在状态为「成功」的微调模型（参见 [模型调优](https://help.aliyun.com/zh/model-studio/fine-tuning/#73749f1ee5634)）。
|
||||
2. **入口路径**：控制台 → **模型** > **模型训练** > **模型压缩** → **创建压缩任务**。
|
||||
3. **配置并提交**：填写必填参数，确认量化模板与校准数据（如需）后单击**开始压缩**；创建后配置不可修改。
|
||||
4. **监控与排查**：
|
||||
- 在任务详情页的**详情**页签查看状态、耗时及错误信息；
|
||||
- 在**日志**页签筛选 ERROR 级别日志，支持下载全量日志用于深度分析；
|
||||
- 失败时优先按 [模型压缩](../../raw/model-user-guide/model-compression/model-compression-introduction.md) 中的“失败排查”步骤处理。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **不可逆性**：压缩操作不可撤销。压缩后模型**不支持继续微调**，也**不支持二次压缩**。务必在提交前确认量化模板选择。
|
||||
- **任务管理限制**：
|
||||
- 仅 `PENDING` 和 `RUNNING` 状态任务可停止；
|
||||
- 仅终态（`SUCCEEDED`/`FAILED`/`CANCELED`）任务可删除；删除任务记录不影响已产出模型。
|
||||
- **失败排查**：优先查看详情页错误信息，再在日志页签搜索 `ERROR` 级别条目；必要时下载全量日志并附任务 ID 提交工单。
|
||||
- **计费说明**：压缩任务本身限时免费（截止时间以控制台公告为准）；压缩后模型的部署费用按 MU 规格单独计费，不受免费期影响。
|
||||
- **精度权衡**：量化必然引入一定精度损失。若部署后效果不达标，应更换量化模板或补充校准数据后重新压缩，而非尝试修复已压缩模型。
|
||||
- **不可逆性**：压缩后模型不支持继续微调、不支持二次压缩；如需调整，请基于原始全精度微调模型重新发起压缩任务。
|
||||
- **任务管理**：
|
||||
- 仅 `PENDING` 和 `RUNNING` 状态可停止；
|
||||
- 仅终态（`SUCCEEDED`/`FAILED`/`CANCELED`）可删除；删除任务记录不影响已产出模型。
|
||||
- **计费说明**：压缩任务本身限时免费（截止时间以控制台公告为准），但压缩后模型的部署费用始终按 MU 规格计费，与免费期无关。
|
||||
- **精度权衡**：量化必然引入一定精度损失，强烈建议在免费期内对同一源模型尝试多个量化模板，并使用业务测试集验证效果后再正式部署——该实践建议已在 [模型压缩](../../raw/model-user-guide/model-compression/model-compression-introduction.md) 的常见问题中明确强调。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,70 +1,72 @@
|
||||
# model context protocol
|
||||
|
||||
[模型上下文协议](../concepts/mcp.md)（Model Context Protocol, MCP）是阿里云百炼平台提供的标准化接口协议，用于在大模型应用（如智能体、工作流）与外部工具服务之间建立安全、可扩展的双向通信通道。它屏蔽了底层协议差异，支持统一接入官方服务、第三方服务及自定义服务，无需为每个工具单独开发适配逻辑。该协议基于 Anthropic 提出的开源标准 [MCP 官网](https://modelcontextprotocol.io/) 实现，已在百炼平台深度集成。
|
||||
[模型上下文协议](../concepts/mcp.md)（Model Context Protocol, MCP）是阿里云百炼平台提供的标准化接口协议，用于在大模型与外部工具（如地图、搜索、数据库等）之间建立安全、可扩展的信息通道。它屏蔽了底层通信细节，使开发者无需为每个工具单独开发适配器，即可在智能体或工作流中统一接入和管理各类能力。该协议基于 Anthropic 提出的开源标准 [MCP 官方规范](https://modelcontextprotocol.io/) 实现，并针对百炼平台进行了工程化增强与云服务集成。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
MCP 协议本身不绑定特定模型，而是通过百炼平台的**智能体应用**和**工作流应用**间接赋能大模型能力。当前支持以下两类核心使用场景：
|
||||
MCP 本身是协议层，不绑定特定模型，但其调用能力需通过百炼平台的**智能体应用**或**工作流应用**触发。当前支持以下两类使用场景：
|
||||
|
||||
- **智能体应用**：大模型根据对话上下文自动判断是否调用 MCP 服务，并动态生成参数（如 `maps_route`、`maps_weather`）。单个智能体最多可同时配置 5 个 MCP 服务 [官方 MCP 服务](../../raw/application-user-guide/model-context-protocol/official-and-third-party-mcp.md)。
|
||||
- **工作流应用**：需显式添加 MCP 节点并手动指定所用工具（如仅使用 `maps_weather`），输入参数须由上游节点（如大模型节点）结构化输出，输出结果再传递至下游节点处理 [官方 MCP 服务](../../raw/application-user-guide/model-context-protocol/official-and-third-party-mcp.md)。
|
||||
- **智能体应用**：大模型根据自然语言输入自动决策是否调用 MCP 工具及选择具体工具（如 `maps_route`, `web_search`），最多可同时配置 5 个 MCP 服务。详见 [官方 MCP 服务](../../raw/application-user-guide/model-context-protocol/official-and-third-party-mcp.md)。
|
||||
- **工作流应用**：需显式拖入 MCP 节点并手动指定工具（如 `maps_weather`）、输入参数与输出映射，适用于确定性编排任务。
|
||||
|
||||
> **注意**：MCP 服务**不能直接接入千问 API 调用链路**，仅限在百炼平台内构建的智能体或工作流应用中使用 [MCP 常见问题](../../raw/application-user-guide/model-context-protocol/mcp-faq.md)。
|
||||
支持的 MCP 服务分为两类：
|
||||
- **官方 MCP 服务**：由阿里云百炼预部署并托管，包括 Amap Maps、Firecrawl、WebSearch、Sequential Thinking、QuickChart 等，开通即用，部分服务限时免费（如 Amap Maps）[原文标题](../../raw/application-user-guide/model-context-protocol/official-and-third-party-mcp.md)。
|
||||
- **自定义 MCP 服务**：支持三种部署方式：① 使用脚本（npx/uvx）部署开源或自研 MCP Server；② 通过 AI 网关将现有 RESTful API 封装为 MCP；③ 通过 OpenAPI 开发者门户将阿里云产品（如 OSS、ECS）发布为 MCP 服务 [原文标题](../../raw/application-user-guide/model-context-protocol/custom-mcp.md)。
|
||||
|
||||
> **注意**：文档 3 和文档 5 均提及“Amap Maps 服务限时免费”，但文档 1 的计费说明中未明确标注该服务是否收费。实际以控制台开通页实时显示为准，建议以 [官方 MCP 服务](../../raw/application-user-guide/model-context-protocol/official-and-third-party-mcp.md) 中的说明为最新依据。
|
||||
|
||||
## 关键参数
|
||||
|
||||
MCP 服务配置与调用涉及以下关键参数，需在不同环节准确设置：
|
||||
MCP 服务配置与调用涉及以下核心参数：
|
||||
|
||||
| 参数类别 | 参数名 | 说明 | 示例值 |
|
||||
| 参数类别 | 字段名 | 说明 | 示例值 |
|
||||
|----------|--------|------|--------|
|
||||
| **服务元信息** | `服务名称` / `描述` | 仅用于控制台识别，不影响模型调用逻辑 | `"长期记忆"` / `"记录并检索个性化信息"` |
|
||||
| **连接方式** | `type` | 必须与端点路径严格匹配，否则触发 `MCP_SERVER_HTTP_METHOD_NOT_ALLOWED` 错误 | `"sse"`（对应 `/sse`）、`"streamableHttp"`（对应 `/mcp`） |
|
||||
| **部署配置** | `command` / `args` | `npx` 或 `uvx` 部署时必需，指定启动命令与包名 | `"npx"`, `["-y", "@modelcontextprotocol/server-memory"]` |
|
||||
| **远程服务** | `url` | HTTP/SSE 服务地址，必须可公网访问且 TLS 有效 | `"https://your-server.com/sse"` |
|
||||
| **鉴权凭证** | 环境变量或 KMS 凭据 | 敏感字段（如 `AMAP_MAPS_API_KEY`）需通过 KMS 加密存储，禁止明文填写 [官方 MCP 服务](../../raw/application-user-guide/model-context-protocol/official-and-third-party-mcp.md) | `YOUR_ENV_KEY: YOUR_ENV_VALUE` |
|
||||
| **服务元信息** | `服务名称`、`描述` | 仅用于平台内标识，不影响模型调用逻辑 | `"高德地图"`、`"提供地理信息与路线规划"` |
|
||||
| **部署配置** | `安装方式` | 决定启动方式：`npx`（Node.js）、`uvx`（Python）、`http`（远程 SSE） | `"npx"` |
|
||||
| | `部署方式` | `基础模式`（按次计费，有冷启动延迟）或 `极速模式`（常驻计费，低延迟） | `"基础模式：按次计费"` |
|
||||
| | `部署地域` | 函数计算 FC 托管地域，影响网络延迟 | `"北京"` |
|
||||
| **协议端点** | `type` | 必须与后端端点严格匹配：`"sse"` 对应 `/sse`，`"streamableHttp"` 对应 `/mcp` | `"streamableHttp"` |
|
||||
| | `url` | 远程 MCP Server 地址（HTTP 模式）或本地命令配置（stdio 模式） | `"https://your-server/mcp"` 或 `{ "command": "npx", "args": ["@mcp/server-memory"] }` |
|
||||
| **鉴权与安全** | `KMS 凭据` | 敏感参数（如 API Key）必须通过 KMS 加密，不可明文填写 | — |
|
||||
| | `DASHSCOPE_API_KEY` | 外部调用时必需的百炼平台认证凭证 | `"sk-xxx"` |
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 1. 接入官方 MCP 服务
|
||||
开通后即可在智能体/工作流中直接选择使用。以 Amap Maps 为例：
|
||||
- 进入 [MCP 广场](https://bailian.console.aliyun.com/?tab=mcp#/mcp-market)，点击卡片 → **立即开通**；
|
||||
- 在智能体配置页添加该服务，或在工作流中拖入 MCP 节点并选择 `maps_weather` 工具。
|
||||
### 1. 平台内集成（智能体/工作流）
|
||||
- **开通服务**：前往 [MCP 广场](https://bailian.console.aliyun.com/?tab=mcp#/mcp-market)，选择服务卡片 → “立即开通”。
|
||||
- **添加至应用**：
|
||||
- *智能体*：在应用编辑页 → “MCP 服务” → 选择已开通服务 → 保存。
|
||||
- *工作流*：从工具栏拖入 “MCP 节点” → 选择服务 → 指定工具 → 配置输入/输出变量映射。
|
||||
- **测试验证**：在智能体对话框或工作流测试面板中发送符合工具语义的指令（如 `查询杭州天气`），观察是否触发调用 [原文标题](../../raw/application-user-guide/model-context-protocol/official-and-third-party-mcp.md)。
|
||||
|
||||
### 2. 外部调用（第三方集成）
|
||||
支持两种模式：
|
||||
- **一键配置**：对接 Cherry Studio、Cursor 等 IDE，自动注入 `DASHSCOPE_API_KEY` 和服务元数据；
|
||||
- **SDK 编码集成**：使用 `mcp` SDK + OpenAI 兼容客户端，通过 `streamablehttp_client` 连接 `/mcp` 端点，实现工具发现与调用循环 [外部调用](../../raw/application-user-guide/model-context-protocol/mcp-external-calls.md)。
|
||||
### 2. 外部调用（第三方应用或 SDK）
|
||||
- **一键集成**：对 Cherry Studio、Cursor 等支持 MCP 的客户端，可在服务详情页选择对应客户端 → “一键配置”，自动注入 `DASHSCOPE_API_KEY` 与服务元数据。
|
||||
- **SDK 编码集成**：
|
||||
- 安装 `mcp` 和 `openai` 客户端库；
|
||||
- 使用 `streamablehttp_client` 连接 MCP Server（URL 格式：`https://dashscope.aliyuncs.com/api/v1/mcps/{service-name}/mcp`）；
|
||||
- 通过 `ClientSession.list_tools()` 获取工具列表，转换为 OpenAI 兼容格式后传入 `chat.completions.create` 的 `tools` 参数；
|
||||
- 在工具调用循环中使用 `session.call_tool()` 执行具体操作。
|
||||
|
||||
### 3. 自定义部署
|
||||
提供三种路径：
|
||||
- **脚本部署**（`npx`/`uvx`）：适用于 Node.js/Python 开发的 MCP 服务包；
|
||||
- **AI 网关导入**：将现有 RESTful API 封装为 MCP 工具；
|
||||
- **OpenAPI 导入**：将阿里云产品 OpenAPI（如 OSS、ECS）发布为 MCP 服务 [自定义 MCP 服务](../../raw/application-user-guide/model-context-protocol/custom-mcp.md)。
|
||||
完整示例见 [外部调用](../../raw/application-user-guide/model-context-protocol/mcp-external-calls.md) 文档中的 Python SDK 代码片段。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **网络与权限限制**：
|
||||
- 自定义 MCP 服务运行于函数计算 FC，**无法访问本地资源（文件、硬件）或用户私有数据库**；
|
||||
- 若需访问云数据库等远程资源，必须配置 FC 的 IP 白名单或 VPC 打通 [MCP 常见问题](../../raw/application-user-guide/model-context-protocol/mcp-faq.md)。
|
||||
|
||||
- **协议与兼容性**：
|
||||
- 百炼已全面升级至 **Streamable HTTP 协议**（`/mcp`），旧版 SSE（`/sse`）仍支持但需确保 `type` 与路径匹配，否则报错 `11200058`；
|
||||
- 自定义服务若使用私有 npm 仓库，**暂不支持直接部署**，需发布至公共仓库或改用 SSE 连接 [MCP 常见问题](../../raw/application-user-guide/model-context-protocol/mcp-faq.md)。
|
||||
|
||||
- **计费与限流**：
|
||||
- 官方服务（如联网搜索）有免费额度（2000 次/月）和 QPS 限制（15 QPS，主账号与 RAM 子账号共享）；
|
||||
- 自定义服务按模式计费：基础模式按调用时长（0.000156 元/秒），极速模式另收部署费（0.000036 元/秒） [模型上下文协议（MCP）](../../raw/application-user-guide/model-context-protocol/mcp-introduction.md)。
|
||||
|
||||
- **调试建议**：
|
||||
- 遇到连接失败（如 `MCP_CONNECTION_REFUSED`），优先执行 `curl <服务地址>` 测试连通性；
|
||||
- 工具调用失败时，检查提示词是否明确声明工具名称与能力，避免模型因意图模糊而跳过调用 [MCP 常见问题](../../raw/application-user-guide/model-context-protocol/mcp-faq.md)。
|
||||
- **模型兼容性**：MCP 仅支持集成于百炼平台的**智能体应用**或**工作流应用**，**不可直接用于调用千问 API**（如 `qwen-max` 的 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)）[原文标题](../../raw/application-user-guide/model-context-protocol/mcp-faq.md)。
|
||||
- **网络与权限**：
|
||||
- 自定义 MCP 服务托管于函数计算 FC，**无固定出口公网 IP**，访问云数据库等资源需配置 IP 白名单或 VPC 打通；
|
||||
- **不支持访问用户本地资源**（如本地文件、硬件设备），此类服务应在本地部署。
|
||||
- **部署约束**：
|
||||
- 私有 npm/PyPI 仓库的包暂不支持直接 `npx`/`uvx` 部署，需发布至公共仓库或改用 `http` 方式；
|
||||
- `npx`/`uvx` 部署的服务版本更新后**不会自动同步**，需手动重新部署。
|
||||
- **错误处理**：常见错误码（如 `11200044` 连接拒绝、`11200051` 限流、`11200054` 协议解析失败）均有明确排查路径，优先使用 `curl` 测试端点连通性，并检查 `type` 与 URL 路径是否匹配（`/sse` vs `/mcp`）。
|
||||
- **[Token](../concepts/token.md) 开销**：MCP 调用返回的内容会作为上下文输入模型，**直接增加输入 [Token](../concepts/token.md) 数量**；同时可能因上下文更丰富而间接增加输出 [Token](../concepts/token.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [模型上下文协议（MCP）](../../raw/application-user-guide/model-context-protocol/mcp-introduction.md)
|
||||
- [官方 MCP 服务](../../raw/application-user-guide/model-context-protocol/official-and-third-party-mcp.md)
|
||||
- [自定义 MCP 服务](../../raw/application-user-guide/model-context-protocol/custom-mcp.md)
|
||||
- [外部调用](../../raw/application-user-guide/model-context-protocol/mcp-external-calls.md)
|
||||
- [MCP 常见问题](../../raw/application-user-guide/model-context-protocol/mcp-faq.md)
|
||||
- [自定义 MCP 服务](../../raw/application-user-guide/model-context-protocol/custom-mcp.md)
|
||||
- [官方 MCP 服务](../../raw/application-user-guide/model-context-protocol/official-and-third-party-mcp.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,61 +1,42 @@
|
||||
# model data overview
|
||||
|
||||
百炼平台的模型数据管理功能为开发者提供统一的数据集创建、处理与回流能力，支撑模型训练、评测及持续优化。本文档系统梳理了支持的数据类型、关键格式规范、使用路径及约束条件，适用于华北2（北京）和新加坡地域。所有操作均需通过[数据管理](https://bailian.console.aliyun.com/#/efm/model_data)控制台入口进行。
|
||||
百炼平台的模型数据管理功能为开发者提供统一的数据集创建、处理与回流能力，支撑模型训练、评测及持续优化。本文档系统梳理了支持的模型类型、关键参数规范、使用方式及重要限制，适用于华北2（北京）和新加坡地域。所有操作均需通过[数据管理](https://bailian.console.aliyun.com/#/efm/model_data)控制台进行。
|
||||
|
||||
## 支持的模型/功能
|
||||
## 支持的模型与功能
|
||||
|
||||
百炼支持三类核心数据用途：**训练集**（用于模型调优）、**评测集**（用于效果评估）和**日志回流数据集**（从SLS推理日志生成结构化训练/评测数据）。
|
||||
- **训练集**支持四种范式：
|
||||
- **SFT**（监督微调）：覆盖文本生成、多模态理解（Qwen-VL）、图生视频（首帧/首尾帧）；
|
||||
- **DPO**（直接偏好优化）：仅限文本生成场景；
|
||||
- **CPT**（持续预训练）：纯文本格式；
|
||||
- **思考模型（Thinking）**：SFT与DPO均支持`<think>`标签格式，但仅对最后一轮assistant输出生效。
|
||||
- **评测集**当前仅支持**文本生成单轮对话**格式（Excel或JSONL），用于自动化或人工评分。
|
||||
- **日志回流**可将SLS推理日志转化为SFT/DPO/CPT训练集或文本生成评测集，详见[日志回流](../../raw/model-user-guide/model-data-overview/model-log-backflow.md)。
|
||||
> **注意**：数据清洗与增强功能[仅支持SFT-文本生成训练集](../../raw/model-user-guide/model-data-overview/data-processing.md)，明确不支持SFT-图片理解、DPO及CPT格式，与文档1中“支持多模态理解训练集”的宽泛表述存在范围差异，实际使用请以文档2为准。
|
||||
百炼支持三类核心数据用途：**训练集**（用于模型调优）、**评测集**（用于模型评估）和**日志回流生成的数据集**（从推理日志转化而来）。
|
||||
- **训练集**支持文本生成（SFT/DPO/CPT）、[多模态](../concepts/multi-modal.md)理解（Qwen-VL系列）、图生视频（首帧/首尾帧）等场景；其中[SFT-文本生成训练集](../../raw/model-user-guide/model-data-overview/training-set-and-evaluation-set.md)是数据处理功能的唯一支持格式，而[SFT-图片理解训练集](../../raw/model-user-guide/model-data-overview/data-processing.md)和[DPO-文本生成训练集](../../raw/model-user-guide/model-data-overview/data-processing.md)暂不支持清洗与增强。
|
||||
- **评测集**当前仅支持文本生成单轮对话格式（Excel或JSONL），用于模型效果量化评估。
|
||||
- **日志回流**可将SLS推理日志结构化为训练集（SFT/DPO/CPT）或评测集，但[日志回流](../../raw/model-user-guide/model-data-overview/model-log-backflow.md)功能在除华北2（北京）和新加坡外的Region不可用，且评测集不支持OSS挂载存储。
|
||||
|
||||
> **注意**：文档1称“目前支持文本生成、[多模态](../concepts/multi-modal.md)理解、图生视频（首帧）、图生视频（首尾帧）训练集”，而文档2明确指出“数据处理仅支持SFT-文本生成训练集”，二者无矛盾——前者描述数据集类型，后者限定数据处理功能的适用范围。但文档2中“暂不支持[SFT-图片理解训练集]”与文档1中“SFT 视觉理解（千问VL）”存在功能覆盖差异，实际使用时需以控制台可用选项为准。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 适用场景 | 类型 | 必填 | 说明 |
|
||||
|------|----------|------|------|------|
|
||||
| `loss_weight` | SFT（所有assistant行）、SFT-Thinking（仅末轮）、DPO（`chosen`字段） | float | 否 | 范围`0.0~1.0`，权重越高训练时影响越大；属邀测参数，需联系商务经理开通。 |
|
||||
| `resized_width`/`resized_height` | 多模态训练（图像/视频帧） | int | 否 | 指定缩放尺寸，单位像素；图像单边≤1024px，视频帧分辨率≤4096×4096。 |
|
||||
| `fps`/`sample_fps` | 视频训练（VL模型） | float | 否 | `fps`用于视频文件路径模式，`sample_fps`用于图片帧列表模式；仅Qwen3.5+ VL模型支持。 |
|
||||
| `video_start`/`video_end` | 视频截取 | float | 否 | 单位秒，需满足`0 ≤ start < end ≤ 视频总时长`。 |
|
||||
| `foreignKey` | 数据增强输出 | string | — | 系统自动生成标识字段，不影响训练，无需手动删除。 |
|
||||
- **`loss_weight`**：用于SFT和DPO训练数据中调节样本重要性，取值范围`0.0 ~ 1.0`，数值越大权重越高。该参数为邀测功能，需联系商务经理开通。
|
||||
- **`resized_width` / `resized_height`**：[多模态](../concepts/multi-modal.md)训练中图像/视频帧的缩放尺寸（像素），影响模型输入分辨率，需与目标模型要求匹配（如Qwen2.5-VL使用绝对坐标，Qwen3-VL使用`[0,999]`相对坐标）。
|
||||
- **`fps` / `sample_fps`**：视频训练中帧率参数，`fps`用于视频文件路径模式，`sample_fps`用于图片帧列表模式，仅Qwen3.5+ VL模型支持。
|
||||
- **`foreignKey`**：数据增强节点自动添加的标识字段，不影响模型训练，无需手动删除。
|
||||
- **时间范围与API Key过滤**：日志回流任务中必填参数，修改时间范围会联动重置API Key和模型选择，需严格按顺序配置。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **创建数据集**：
|
||||
- 训练/评测集：上传ZIP（含`data.jsonl`根目录文件）或Excel，格式严格遵循[训练集与评测集](../../raw/model-user-guide/model-data-overview/training-set-and-evaluation-set.md)要求；
|
||||
- 日志回流：在[模型监控](https://bailian.console.aliyun.com/#/model-telemetry)页开启审计日志与推理日志后，配置时间范围、API Key、模型等参数生成结构化数据集。
|
||||
|
||||
2. **数据处理**：
|
||||
- 仅SFT文本训练集支持清洗（如敏感信息打码、URL移除）与增强（Few-Shot生成）；
|
||||
- 通过[数据管理](https://bailian.console.aliyun.com/?tab=model#/efm/model_data) > 数据流 > 创建任务，选择预置模板或自定义节点链路；
|
||||
- 处理后生成独立版本（如V1→V2），原数据集不受影响。
|
||||
|
||||
3. **版本管理**：
|
||||
- 所有操作（上传、清洗、增强、日志回流）均生成新版本，支持按版本回溯与对比；
|
||||
- OSS挂载数据集不支持“新增版本”，需通过“导入数据”页追加；平台存储数据集支持此操作。
|
||||
1. **数据集创建**：通过[数据管理](https://bailian.console.aliyun.com/#/efm/model_data)上传ZIP包（训练集）或Excel/JSONL文件（评测集），注意压缩包内`data.jsonl`必须位于根目录，图片/视频文件名全局唯一。
|
||||
2. **数据清洗与增强**：仅适用于SFT文本生成训练集。在数据流画布中组合“数据清洗”（如敏感信息打码）和“数据增强”（如Few-Shot生成）节点，发布后启动任务，处理结果自动生成新版本（如V1→V2），原数据不受影响。
|
||||
3. **日志回流**：需先在[模型监控](https://bailian.console.aliyun.com/#/model-telemetry)完成审计日志与推理日志的授权及开启，再通过任一入口（模型监控页、详情页或数据管理页）配置回流参数。单次上限10万条，支持多次追加至同一数据集的不同版本。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域限制**：所有功能默认仅限华北2（北京），日志回流额外支持新加坡Region；其他地域不可用。
|
||||
- **文件约束**：
|
||||
- ZIP包最大2GB，文件名仅支持ASCII字母、数字、`_`、`-`；
|
||||
- `data.jsonl`必须位于ZIP根目录；
|
||||
- 图像单张≤10MB，格式限`.bmp/.jpeg/.jpg/.png/.tif/.tiff/.webp`；
|
||||
- 图生视频训练集图像/视频分辨率≤4096×4096。
|
||||
- **数量限制**：
|
||||
- 日志回流单次上限10万条（可多次追加）；
|
||||
- 数据增强-通用单次最多生成2000条样本；
|
||||
- SFT训练集建议≥1000条优质样本，CPT需≥1000万[Token](../concepts/token.md)。
|
||||
- **格式兼容性**：
|
||||
- SFT ChatML不支持OpenAI `name`/`weight`字段；
|
||||
- VL模型`system`消息`content`必须为数组格式`[{"text":"..."}]`，禁用字符串；
|
||||
- DPO数据中`chosen`/`rejected`内容需严格匹配`messages`末轮user输入语义。
|
||||
> **注意**：文档1中提及“支持图生视频（首帧）与（首尾帧）训练集”，但文档3明确日志回流**仅支持文本生成场景**，图生视频类日志无法回流，二者能力边界需严格区分。
|
||||
- **地域限制**：所有功能默认仅限华北2（北京）；日志回流额外支持新加坡Region。
|
||||
- **格式与规模**：
|
||||
- SFT训练集最小需**上千条优质样本**，CPT需**千万级[Token](../concepts/token.md)预训练数据**；DPO一般需**上百条人类偏好数据**。
|
||||
- ZIP包最大2GB（训练集）或20MB（图生视频`data.jsonl`），图片单张≤1024px且≤10MB，视频≤4096×4096。
|
||||
- **功能边界**：
|
||||
- 数据处理不支持多模态或DPO训练集；
|
||||
- 日志回流评测集不支持OSS挂载；
|
||||
- 图生视频验证集无需提供视频文件，由平台自动调用模型生成预览。
|
||||
- **版本管理**：数据清洗、增强及日志回流均生成独立版本，不会覆盖原始数据集，但名称与描述创建后不可修改。
|
||||
- **费用与运维**：开启推理日志会产生SLS存储与读写费用，长期不用应及时关闭；OSS挂载需额外授权两个服务角色。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,59 +1,48 @@
|
||||
# model deployment 1
|
||||
|
||||
百炼平台的 `model deployment 1` 是面向生产环境的模型服务化能力，支持将预置模型或用户调优/导入的 LoRA 模型部署为资源独占、性能可保障的专属推理服务。该能力提供三种计费与资源调度模式：预置吞吐（PTU）、模型单元（MU）和按 [Token](../concepts/token.md) 用量计费，分别适用于高并发低延迟、定制化性能隔离、以及低成本效果验证等典型场景。部署后可通过标准 API（OpenAI 兼容/DashScope）调用，所有模式均需通过控制台或 API 显式创建。
|
||||
model deployment 1 是百炼平台面向生产环境的模型服务化能力，提供三种核心计费与资源隔离模式：预置吞吐（PTU）、模型单元（MU）和按 [Token](../concepts/token.md) 用量计费。开发者可根据业务对吞吐稳定性、延迟敏感度、成本弹性及模型定制程度的要求，选择最适配的部署方式。所有模式均支持通过控制台或 API 快速创建、扩缩容与监控，且计费方式在创建后不可变更。
|
||||
|
||||
## 支持的模型与功能
|
||||
## 支持的模型/功能
|
||||
|
||||
- **预置模型**：覆盖千问（Qwen）全系列（如 `qwen3.7-plus-2026-05-26`、`qwen-flash-2025-07-28`）、DeepSeek（`deepseek-v4-flash`、`deepseek-v4-pro`）、GLM（`glm-5.1`、`glm-5.2`）、千问 VL（`qwen3-vl-plus-2025-09-23`）等，详见 [模型部署简介](../../raw/model-user-guide/model-deployment-1/model-deployment-introduction.md) 中的计费表格。
|
||||
- **调优后模型**：支持全部通过百炼平台完成 SFT/LoRA 调优的模型，部署时需使用其模型 ID（如 `qwen3-8b-ft-202511132025-0260`）。
|
||||
- **导入模型**：仅支持从阿里云 OSS 导入符合约束的 LoRA 模型，基础模型须在 [模型导入](../../raw/model-user-guide/model-deployment-1/model-import.md) 所列清单内（如 `千问3-8B`、`千问3-VL-8B-Instruct`），且必须满足 rank ∈ {8,16,32,64}、词汇表与 chat_template 未修改、视觉模型 VIT 冻结等要求。
|
||||
- **核心功能**：
|
||||
- PTU 模式支持长输入（最高 256K token）与前缀缓存，通过阶梯系数与缓存折扣优化额度消耗；
|
||||
- MU 模式支持 PD 分离计算模式（降低首 [Token](../concepts/token.md) 延迟）、自定义推理模式（Instruct/Thinking）、最长上下文长度及 RPM/TPM 限流；
|
||||
- [Token](../concepts/token.md) 计费模式仅支持部分 LoRA 调优模型，用于效果验证。
|
||||
- **预置吞吐（PTU）**：适用于高并发、低延迟、流量可预估的生产场景，支持长输入（最高 256K token）与前缀缓存优化额度消耗，当前支持 `glm-5.1`、`deepseek-v4-pro`、`qwen3.7-plus-2026-05-26` 等模型，详见[预置吞吐长输入与缓存](../../raw/model-user-guide/model-deployment-1/ptu-long-input-and-cache.md)。
|
||||
- **模型单元（MU）**：适用于需资源独占、性能自定义（如 PD 分离、思考模式、最长上下文、RPM/TPM 限流）的私有化推理场景，支持全部千问系列、GLM、DeepSeek、千问VL 及 CosyVoice 等模型，覆盖 Instruct/Thinking 模式与[多模态](../concepts/multi-modal.md)任务。
|
||||
- **按 [Token](../concepts/token.md) 用量计费**：仅限 LoRA 微调后的自定义模型（如 `qwen3-8b-ft-*`），适用于效果验证、低频调用或成本优先型实验场景，不支持预置吞吐或模型单元的性能配置能力。
|
||||
|
||||
> **注意**：文档 1 中称“部分经过 LoRA 调优后的模型”支持 Token 计费，而文档 4 明确指出“仅支持导入 LoRA 模型”，且文档 3 的 API 示例中 `plan: "lora"` 实际对应 Token 计费模式。三者一致指向 LoRA 模型是 Token 计费的必要前提，但文档 1 表格中“支持模型”列对 Token 计费的描述（“部分经过 LoRA 调优后的模型”）易引发歧义，应以实际 API 参数 `plan: "lora"` 和文档 4 的约束为准。
|
||||
> **注意**：文档 3 中“支持模型”表格将 `qwen3.7-plus-2026-05-26` 归类为 PTU 和 MU 均支持，但文档 1 明确其支持前缀缓存与长输入阶梯系数，而文档 4 的 API 示例中仅将其用于 MU 部署；实际以控制台实时可选列表为准，API 创建时若指定不支持的 `plan` 会返回 400 错误。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数名 | 适用模式 | 说明 | 示例值 |
|
||||
|--------|----------|------|--------|
|
||||
| `plan` | 所有模式 | 部署计费计划类型 | `"ptu"` / `"mu"` / `"lora"` |
|
||||
| `ptu_capacity` | PTU | 预置吞吐容量，含 `input_tpm` 和 `output_tpm`（单位：token/分钟） | `{"input_tpm": 10000, "output_tpm": 1000}` |
|
||||
| `deploy_spec` / `model_unit_spec` | MU | 模型单元规格，如 `"MU1 x 8"`、`"MU3 x 16"` | `"MU1 x 8"` |
|
||||
| `enable_thinking` | MU | 是否启用思考模式（影响计费单价与输出行为） | `true` |
|
||||
| `max_context_length` | MU | 最长上下文长度（需模型支持） | `10000` |
|
||||
| `rpm_limit` / `tpm_limit` | MU | 服务级限流阈值 | `500`, `1000` |
|
||||
| `capacity` | MU & Token | MU 模式下副本数；Token 模式下为占位参数（必须填，但无效） | `4`, `1` |
|
||||
| 参数名 | 适用模式 | 说明 | 来源依据 |
|
||||
|--------|----------|------|----------|
|
||||
| `ptu_capacity.input_tpm` / `output_tpm` | PTU | 输入/输出每分钟 [Token](../concepts/token.md) 数（KTPM），决定额度购买量，影响长输入阶梯系数应用范围 | [预置吞吐长输入与缓存](../../raw/model-user-guide/model-deployment-1/ptu-long-input-and-cache.md) |
|
||||
| `deploy_spec` / `capacity` / `enable_thinking` / `max_context_length` | MU | 模型单元规格（如 `MU1`）、副本数、是否启用思考模式、最长上下文长度（部分模型支持） | [使用 API或命令行进行模型部署](../../raw/model-user-guide/model-deployment-1/model-deployment-quick-start.md) |
|
||||
| `plan: "lora"` | Token 用量 | 仅用于 LoRA 微调模型，`capacity` 字段必须填写但无效，扩缩容需走控制台人工审核 | [使用 API或命令行进行模型部署](../../raw/model-user-guide/model-deployment-1/model-deployment-quick-start.md) |
|
||||
| `rpm_limit` / `tpm_limit` | MU（可选） | 服务级请求/Token 每分钟限流阈值，防止突发流量冲击 | [模型部署](../../raw/model-user-guide/model-deployment-1/model-deployment-introduction.md) |
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **控制台部署**：前往 [模型部署控制台](https://bailian.console.aliyun.com/cn-beijing/?tab=model#/efm/model_deploy/create)，选择模型、计费方式及对应配置（如 PTU 容量、MU 规格、限流值等），提交即可。详细步骤见 [模型部署简介](../../raw/model-user-guide/model-deployment-1/model-deployment-introduction.md)。
|
||||
- **API 部署**：使用 DashScope API 发起 HTTP POST 请求。例如：
|
||||
- PTU 模式：`curl -X POST ... --data '{"name":"my_qwen_flash","model_name":"qwen-flash-2025-07-28","plan":"ptu","ptu_capacity":{"input_tpm":10000,"output_tpm":1000}}'`
|
||||
- MU 模式：`curl -X POST ... --data '{"name":"my_qwen_plus","model_name":"qwen-plus-2025-12-01","plan":"mu","deploy_spec":"MU1","enable_thinking":true}'`
|
||||
- Token 模式：`curl -X POST ... --data '{"model_name":"qwen3-8b-ft-202511132025-0260","plan":"lora","capacity":1,"name":"qwen3-8b-ft"}'`
|
||||
具体参数与响应格式详见 [使用 API或命令行进行模型部署](../../raw/model-user-guide/model-deployment-1/model-deployment-quick-start.md)。
|
||||
- **调用方式**：部署成功（状态为 `RUNNING`）后，使用 `model_name`（即部署服务名）调用 DashScope Generation API 或 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)，确保 API Key 所属业务空间与部署空间一致。
|
||||
- **控制台操作**：前往[模型部署控制台](https://bailian.console.aliyun.com/#/efm/model_deploy/create)，选择模型、计费方式及对应参数（如 PTU 容量、MU 规格、推理模式），提交即完成部署；状态变为 `RUNNING` 后即可调用。
|
||||
- **API 调用**：使用 DashScope SDK 或 HTTP 请求 `POST /api/v1/deployments`，按 `plan` 字段区分模式：
|
||||
- PTU：传 `"plan": "ptu"` + `ptu_capacity` 对象；
|
||||
- MU：传 `"plan": "mu"` + `deploy_spec`, `capacity`, `enable_thinking` 等字段；
|
||||
- Token 用量：传 `"plan": "lora"` + `model_name`（LoRA 模型 ID）。
|
||||
详细字段与示例见[使用 API或命令行进行模型部署](../../raw/model-user-guide/model-deployment-1/model-deployment-quick-start.md)。
|
||||
- **调用地址**：部署成功后，专属服务 ID（`deployed_model`）即为模型名称，直接用于 `Generation.call(model='xxx', ...)` 或 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域限制**：API 部署仅支持华北2（北京）地域，见 [使用 API或命令行进行模型部署](../../raw/model-user-guide/model-deployment-1/model-deployment-quick-start.md) 前提条件。
|
||||
- **权限要求**：API 调用需确保 API Key 所属业务空间已授权目标模型的部署权限，否则返回 `Workspace xxx does not have deployment privilege for model xxxx` 错误；主账号与子账号的 OSS 授权流程不同，子账号需主账号预先授予 `ram:CreateServiceLinkedRole` 权限，详见 [模型导入](../../raw/model-user-guide/model-deployment-1/model-import.md)。
|
||||
- **计费约束**：
|
||||
- PTU 模式：计费方式创建后不可更改；溢出策略（自动溢出/仅使用 PTU）决定超限行为（转按量计费或返回 429）；长输入超出模型上限（如千问 128K）仍自动转为按量计费。
|
||||
- MU 模式：模型单元-后付费资源“先买到先得”，购买失败全额退款；PD 分离模式需显式选择 `deploy_spec`（如 `MU1 x 16`）。
|
||||
- Token 模式：仅支持 LoRA 模型，且 `capacity` 参数无效，扩缩容需通过控制台申请。
|
||||
- **模型约束**：
|
||||
- OSS 导入的 LoRA 模型不支持增量训练；
|
||||
- 导入模型文件必须包含 `adapter_model.safetensors`、`adapter_config.json`、`config.json`，且 rank、词汇表、chat_template 必须与基础模型一致；
|
||||
- 视觉语言模型导入时，VIT 部分必须冻结（`safetensors` 中不能含 `visual.` 开头的权重键）。
|
||||
- **计费不可变**：部署创建后无法切换计费方式，需下线重部署。
|
||||
- **PTU 溢出策略**：创建时须明确选择「自动溢出」（转按量计费，响应头含 `x-dashscope-ptu-overflow:true`）或「仅使用 PTU 容量」（超限返回 429），后者可能导致服务中断。
|
||||
- **长输入上限**：模型物理上限严格（如千问 128K、DeepSeek 64K、GLM-5.2 1M），超出即强制转为按量计费，不受 PTU 阶梯系数约束。
|
||||
- **LoRA 导入约束**：仅支持从 OSS 导入符合 rank（8/16/32/64）、词汇表一致、chat_template 未修改、VIT 冻结等要求的 SafeTensors 格式模型，详见[模型导入](../../raw/model-user-guide/model-deployment-1/model-import.md)。
|
||||
- **地域限制**：API 部署仅支持华北2（北京）地域，其他地域需切换 endpoint 或使用控制台。
|
||||
- **权限隔离**：API Key 必须归属拥有目标模型部署权限的业务空间，否则报 `Workspace xxx does not have deployment privilege` 错误。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [模型部署](../../raw/model-user-guide/model-deployment-1/model-deployment-introduction.md)
|
||||
- [预置吞吐长输入与缓存](../../raw/model-user-guide/model-deployment-1/ptu-long-input-and-cache.md)
|
||||
- [使用 API或命令行进行模型部署](../../raw/model-user-guide/model-deployment-1/model-deployment-quick-start.md)
|
||||
- [模型导入](../../raw/model-user-guide/model-deployment-1/model-import.md)
|
||||
- [模型部署](../../raw/model-user-guide/model-deployment-1/model-deployment-introduction.md)
|
||||
- [使用 API或命令行进行模型部署](../../raw/model-user-guide/model-deployment-1/model-deployment-quick-start.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,57 +1,61 @@
|
||||
# model evaluation introduction
|
||||
|
||||
模型评测是百炼平台提供的模型能力量化评估功能，支持通过自定义或基线方式对文本生成类模型的推理结果进行多维度打分与对比。它帮助开发者在模型选型、调优验证、质量监控等场景中基于客观指标做出技术决策。该功能不提供 API/SDK 接口，当前仅支持控制台操作。
|
||||
模型评测是百炼平台提供的模型能力量化评估功能，支持通过自定义或基线方式对文本生成类模型进行多维度打分与对比。它帮助开发者在模型选型、调优验证、质量监控等场景中，基于客观指标（如综合得分、通过率、分数分布）做出技术决策。该功能不提供 API/SDK 接口，当前仅支持控制台操作。
|
||||
|
||||
## 支持的模型/功能
|
||||
## 支持的模型与功能
|
||||
|
||||
- **支持模型类型**：仅限文本生成类模型（如 Qwen 系列），不支持多模态、语音、图像等非文本生成模型。预置模型和调优后的模型均可作为被评测对象，具体支持列表参见[预置模型列表](https://help.aliyun.com/zh/model-studio/model-deployment-introduction)。
|
||||
- **核心评测范式**：支持三大类共五种评测维度，覆盖全自动、半自动与人工评审全流程：
|
||||
- *大模型评估*（分类型/数值型）：依赖裁判模型（如千问-Max）进行语义级评判；
|
||||
- *规则评估*（字符串匹配/文本相似度）：基于算法（ROUGE/BLEU/Cosine 等）或确定性逻辑计算得分；
|
||||
- *人工评估-分类型*：由人工逐条标注 Pass/Fail 标签。
|
||||
- **评测模式**：
|
||||
- **自定义评测**：使用用户上传的评测数据集（EvaluationSet 类型）或已有推理结果集，支持全部维度类型、结果下载及排行榜集成；
|
||||
- **基线评测**：仅北京地域可用，使用平台预设公开数据集（如 C-Eval、GSM8K、BBH），系统自动评分，不支持维度配置、结果下载与人工标注。详见[创建基线评测任务](../../raw/model-user-guide/model-evaluation-introduction/model-evaluation-overview.md)。
|
||||
- **支持模型类型**：仅限文本生成类模型（包括预置模型与调优后模型），不支持[多模态](../concepts/multi-modal.md)、语音、向量模型等 [模型评测 (raw/model-user-guide/model-evaluation-introduction/model-evaluation-overview.md)](../../raw/model-user-guide/model-evaluation-introduction/model-evaluation-overview.md)。
|
||||
- **评测方式**：
|
||||
- **自定义评测**：使用用户上传的评测数据集（EvaluationSet 类型）或已有的推理结果集，配合自定义创建的评测维度执行；支持全地域。
|
||||
- **基线评测**：使用平台预置的公开标准数据集（如 C-Eval、GSM8K、BBH 等），系统自动评分；**仅北京地域可用**，且不支持结果下载与人工标注 [模型评测 (raw/model-user-guide/model-evaluation-introduction/model-evaluation-overview.md)](../../raw/model-user-guide/model-evaluation-introduction/model-evaluation-overview.md)。
|
||||
- **评分范式**：共五种评测维度类型，覆盖三大评估范式：
|
||||
- *大模型评估*（数值型/分类型）：依赖裁判模型（如千问-Max）进行语义级评判；
|
||||
- *规则评估*（字符串匹配/文本相似度）：基于算法（ROUGE/BLEU/Cosine 等）或确定性逻辑自动计算；
|
||||
- *人工评估*（分类型）：由人工逐条标注 Pass/Fail 标签 [评测维度 (raw/model-user-guide/model-evaluation-introduction/evaluation-metrics.md)](../../raw/model-user-guide/model-evaluation-introduction/evaluation-metrics.md)。
|
||||
|
||||
> **注意**：文档1称“当前仅支持文本生成类模型评测”，而文档2未明确限定模型类型，但其所有示例与参数说明均围绕文本生成展开，且文档1为更高层级的概览文档，应以文档1为准。
|
||||
> **注意**：文档1称“当前仅支持文本生成类模型评测”，文档2未明确限定模型类型，但其所有示例与参数说明均围绕文本生成展开，且文档2中“适用场景”列（如 Function Calling、NL2SQL、摘要）均为文本任务。二者无实质矛盾，以文档1的明确声明为准。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数类别 | 参数名 | 说明 | 必填性 | 取值约束 |
|
||||
|----------|--------|------|--------|-----------|
|
||||
| **通用** | 维度名称 | 评测维度模板标识符 | 是 | ≤20 字符 |
|
||||
| 参数类别 | 参数名 | 说明 | 必填性 | 约束与建议 |
|
||||
|----------|--------|------|--------|------------|
|
||||
| **通用** | 维度名称 | 维度模板标识符 | 是 | ≤20 字符；建议采用“评估方面+评估方式”命名（如`回答准确性-LLM评分`） |
|
||||
| | 描述 | 补充说明 | 否 | ≤100 字符 |
|
||||
| **大模型评估** | 裁判模型 | 执行评分的 LLM（如千问-Max） | 分类型/数值型必填 | 从下拉列表选择 |
|
||||
| | 评分器 Prompt | 指导裁判模型评分的提示词 | 分类型/数值型必填 | 必含 `${prompt}` / `${output}` / `${completion}` 至少一个变量；≤50000 字符 |
|
||||
| | 评分范围 | 数值型维度的整数打分区间 | 数值型必填 | 最小值 ≥ 0，最大值 ≥ 1，默认 `0~5` |
|
||||
| | 通过阈值 | 判定 Pass 的最低分值（数值型）或相似度（规则型） | 数值型/相似度型必填 | 步长 0.1（数值型）或 0.01（相似度型）；需在有效范围内 |
|
||||
| **规则评估** | 比较操作符（字符串匹配） | 相等 / 不相等 / 包含 | 字符串匹配必填 | — |
|
||||
| | 评估指标（文本相似度） | ROUGE-1/2/L、BLEU、Cosine、Fuzzy Match、Accuracy | 文本相似度必填 | 7 种可选算法 |
|
||||
| **人工评估** | Pass/Fail 标签 | 人工标注的分类标签 | 是 | 标签间互斥，单个标签 ≤20 字符 |
|
||||
|
||||
详细参数配置逻辑与变量引用规则请参见[评测维度](../../raw/model-user-guide/model-evaluation-introduction/evaluation-metrics.md)。
|
||||
| **大模型评估专用** | 裁判模型 | 执行评分的 LLM | 是（仅大模型评估） | 推荐千问-Max；费用按 [Token](../concepts/token.md) 计费 |
|
||||
| | 评分器 Prompt | 指导裁判模型打分的提示词 | 是（仅大模型评估） | 必须含至少一个变量：`${prompt}`、`${output}` 或 `${completion}`；≤50000 字符 |
|
||||
| | 评分范围（数值型） | 整数打分区间 | 是（仅数值型） | 最小值 ≥ 0，最大值 ≥ 1；默认 `0~5`；范围过大（如 >10）会降低评分一致性 |
|
||||
| | 通过阈值 | Pass 判定下限 | 是（数值型/相似度型） | 数值型步长 0.1（如 `3.0`）；相似度型范围 `0~1`，步长 `0.01` |
|
||||
| | Pass/Fail 标签（分类型） | 分类输出标签 | 是（仅分类型） | Pass 与 Fail 标签互斥且不可重复；每标签 ≤20 字符 |
|
||||
| **规则评估专用** | 比较操作符（字符串匹配） | 相等 / 不相等 / 包含 | 是（仅字符串匹配） | 用于 Function Calling、固定答案等确定性场景 |
|
||||
| | 评估指标（文本相似度） | ROUGE-1/ROUGE-L/BLEU/Cosine 等 | 是（仅文本相似度） | 翻译用 BLEU，摘要用 ROUGE-L，语义相关用 Cosine |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **准备数据**：在数据管理模块上传评测集（EvaluationSet 类型），至少包含 `Prompt`（用户问题）和 `Completion`（参考答案）两列；或准备已含 `Output` 的推理结果集文件。
|
||||
2. **创建维度**：在「评测维度」Tab 创建至少一个维度模板。类型一经创建不可修改，选错需删除重建（[原文标题](../../raw/model-user-guide/model-evaluation-introduction/model-evaluation-overview.md)）。
|
||||
3. **创建任务**：
|
||||
- 自定义评测：选择被评测模型、数据来源（评测数据集或推理结果集）、关联维度；可选配置 `System Prompt`（作用于被测模型，非裁判模型）；
|
||||
- 基线评测：仅北京地域可见，选择模型与预设数据集（如 MMLU、HellaSwag）即可提交。
|
||||
4. **查看结果**：任务状态变为「评测完成」后，在详情页「指标统计」Tab 查看综合得分、通过率与分数分布；「数据明细」Tab 查看逐样本评分。人工评估任务需全部标注完成后才进入「评测完成」状态（[原文标题](../../raw/model-user-guide/model-evaluation-introduction/model-evaluation-overview.md)）。
|
||||
5. **复用与优化**：首次评测后下载结果文件，后续任务使用「推理结果集」数据来源可避免重复推理；优先选用规则评估降低裁判模型费用（[原文标题](../../raw/model-user-guide/model-evaluation-introduction/model-evaluation-overview.md)）。
|
||||
1. **准备数据**：在数据管理模块上传 `EvaluationSet` 类型数据集（含 `Prompt` 和 `Completion` 列），或准备已含 `Output` 的推理结果集文件。
|
||||
2. **创建维度**：在「模型评测 > 评测维度」页面创建至少一个维度模板。类型一经创建不可修改，选错需删除重建 [评测维度 (raw/model-user-guide/model-evaluation-introduction/evaluation-metrics.md)](../../raw/model-user-guide/model-evaluation-introduction/evaluation-metrics.md)。
|
||||
3. **创建任务**：
|
||||
- 自定义评测：选择目标模型、数据来源（评测数据集或推理结果集）、关联维度；可选开启排行。
|
||||
- 基线评测：仅北京地域可见，选择模型与预设数据集（如 MMLU、GSM8K）即可提交。
|
||||
4. **查看结果**：任务状态变为「评测完成」后，在详情页「指标统计」Tab 查看综合得分、通过率及分布图；「数据明细」Tab 查看逐条评分。人工评估任务需全部标注完成后才进入完成状态。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域限制**：基线评测仅在北京地域可用，其他地域控制台不显示该选项，属正常行为。
|
||||
- **模型与数据限制**：仅支持文本生成类模型；评测数据集必须为 EvaluationSet 类型且已发布版本；训练集不可用于评测。
|
||||
- **维度不可变性**：评测维度类型创建后不可修改，误选需删除后重建；删除维度前须确保无排行榜绑定（否则阻止新任务创建），且已被任务引用时无法直接删除（[原文标题](../../raw/model-user-guide/model-evaluation-introduction/evaluation-metrics.md)）。
|
||||
- **费用说明**：
|
||||
- 使用「评测数据集」会产生被评测模型的推理费用；
|
||||
- 大模型评估维度（分类型/数值型）产生裁判模型评分费用；
|
||||
- 规则评估与人工评估无裁判模型费用；
|
||||
- 基线评测计费规则与自定义评测一致（按实际 [Token](../concepts/token.md) 消耗计费）。
|
||||
- **结果解读**：综合得分是各维度平均分，可能掩盖维度间差异；建议结合分数分布图分析短板；1–3% 的分差通常属评测噪声，不宜作为决策依据。
|
||||
- **地域限制**：基线评测功能仅在北京地域可用，其他地域控制台不显示该选项，属正常设计 [模型评测 (raw/model-user-guide/model-evaluation-introduction/model-evaluation-overview.md)](../../raw/model-user-guide/model-evaluation-introduction/model-evaluation-overview.md)。
|
||||
- **模型与数据限制**：
|
||||
- 仅支持文本生成类模型；非文本模型无法参与评测。
|
||||
- 评测数据集必须为 `EvaluationSet` 类型且已发布版本；训练集、知识库等类型不可用。
|
||||
- 数据量建议：小规模验证 50–100 条，正式评测 200–500 条，全面评估 ≥500 条。
|
||||
- **费用说明**：
|
||||
- 使用「评测数据集」作为数据源时，产生被评测模型的推理费用（按 [Token](../concepts/token.md) 计费）。
|
||||
- 大模型评估维度（数值型/分类型）额外产生裁判模型评分费用（按 [Token](../concepts/token.md) 计费）；规则评估与人工评估无此费用。
|
||||
- 使用「推理结果集」可规避被评测模型的推理费用。
|
||||
- **配置约束**：
|
||||
- 评测维度类型创建后不可修改；关联该维度的已有任务不受影响，但需删除维度后重建。
|
||||
- 任务提交后不可更换被评测模型或修改维度；出错需删除任务后重建。
|
||||
- 排行榜绑定维度后，若该维度被删除，将阻止新任务创建。
|
||||
- **结果解读建议**：
|
||||
- 避免仅依赖综合得分做决策；应结合分数分布图识别维度间差异（如某维度持续低分暴露能力短板）。
|
||||
- 1–3% 的分数差异通常属评测噪声，不建议据此判断模型优劣。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,44 +1,61 @@
|
||||
# model experience
|
||||
|
||||
`model experience` 是百炼平台面向开发者提供的模型能力概览与使用指南，涵盖文本、视觉、音视频、3D、嵌入与重排序等全模态模型体系。本文档聚焦模型选型逻辑、关键参数配置与工程化接入要点，帮助开发者快速匹配业务场景与最优模型，避免因版本混淆或能力误判导致的集成问题。
|
||||
`model experience` 是百炼平台面向开发者提供的模型能力总览与选型指南，覆盖文本、视觉、音视频、3D、语音、音乐等全模态生成与理解能力。本文档聚焦核心模型能力、关键参数、标准使用方式及硬性约束，不包含营销性描述，所有信息均基于当前稳定版 API 与模型服务规范。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
百炼平台提供覆盖多模态的模型矩阵，按能力维度可划分为以下几类：
|
||||
百炼提供覆盖[多模态](../concepts/multi-modal.md)的模型矩阵，按任务类型组织如下：
|
||||
|
||||
- **文本生成**：以 `qwen3.7-plus` 为旗舰，支持 100 万上下文、Function Calling、内置工具（联网搜索/代码解释器）及结构化 JSON 输出；`qwen3.7-flash` 在效果接近的前提下显著降低成本；超长文档处理推荐 `qwen-long`（1000 万 [Token](../concepts/token.md)）[原文标题](../../raw/model-user-guide/model-experience/text-generation-model.md)。
|
||||
- **视觉理解**：`qwen3.7-plus` 和 `qwen3.7-flash` 同时支持图像、视频（最长 2 小时）、OCR 及结构化输出；专用 OCR 模型 `qwen3.5-ocr` 针对表格与手写内容优化 [原文标题](../../raw/model-user-guide/model-experience/vision-model.md)。
|
||||
- **图片/视频生成与编辑**：`wan2.7-image-pro` 支持文生图（4096×4096）、多图参考编辑；`happyhorse-1.1-t2v` 和 `wan2.7-t2v-2026-06-12` 分别适用于通用文生视频与自定义音频驱动场景 [原文标题](../../raw/model-user-guide/model-experience/image-model.md)。
|
||||
- **语音与音乐**：`qwen-audio-3.0-tts-plus` 支持声音复刻与指令控制；`fun-music-v1` 支持 [prompt](prompt.md)/lyrics 两种输入方式生成带人声歌曲；`qwen3.5-omni-plus-realtime` 实现端到端语音对话与音视频理解 [原文标题](../../raw/model-user-guide/model-experience/tts-model.md)。
|
||||
- **向量与重排序**：`text-embedding-v4` 为文本 Embedding 默认推荐，支持 64–2048 维灵活配置；`qwen3-rerank` 用于 RAG 场景 Top-N 结果精排；跨模态检索推荐 `qwen3-vl-embedding` [原文标题](../../raw/model-user-guide/model-experience/embedding-rerank-model.md)。
|
||||
- **全模态与 S2S**：`qwen3.5-omni-plus` 支持文本/音频/图片/视频四模态输入与文本/语音双模态输出，具备联网搜索与 Function Calling；`qwen-audio-3.0-realtime-plus` 专为低延迟语音助手设计，支持语义 VAD 与 Function Calling [原文标题](../../raw/model-user-guide/model-experience/omni.md)。
|
||||
- **文本生成**：以 `qwen3.7-plus` 为旗舰，支持 1M 上下文、Function Calling、内置工具（联网搜索/代码解释器）和结构化 JSON 输出；`qwen3.7-flash` 在效果接近的前提下显著降低成本；`qwen3.7-max` 和 `qwen3.8-max-preview`（仅 [Token](../concepts/token.md) Plan 可用）适用于复杂推理场景 [原文标题](../../raw/model-user-guide/model-experience/text-generation-model.md)。
|
||||
- **视觉理解**：`qwen3.7-plus` 同时支持图像、视频（最长 2 小时）、OCR 和结构化输出；`qwen3.5-ocr` 专用于高精度文档/手写体文字提取；`qwen3-vl-plus` 等 VL 系列模型支持多图输入与视频理解 [原文标题](../../raw/model-user-guide/model-experience/vision-model.md)。
|
||||
- **图片与视频生成**：`wan2.7-image-pro` 支持文生图（4096×4096）、多图编辑与角色一致性；`happyhorse-1.1-t2v` 和 `wan2.7-t2v-2026-06-12` 分别适用于通用文生视频与带自定义音频的高质量生成；`tripo-p1.0` 和 `tripo-h3.1` 提供文/图/多图生 3D 模型能力，但仅限华北2（北京）地域 [原文标题](../../raw/model-user-guide/model-experience/tripo-3d-generation-guide.md)。
|
||||
- **语音与音乐**：`fun-asr` 系列支持热词增强与说话人分离；`qwen3.5-omni-plus` 支持音视频联合理解与情感识别；`fun-music-v1` 支持 [prompt](prompt.md)/lyrics 双路输入与 gender 控制；`qwen-audio-3.0-tts-plus` 和 `cosyvoice-v3.5-plus` 均支持声音复刻与指令控制（如“温柔语速稍慢”）[原文标题](../../raw/model-user-guide/model-experience/asr-model.md)。
|
||||
- **向量与重排序**：`text-embedding-v4` 为文本 Embedding 默认推荐，支持 64–2048 维可调；`qwen3-vl-embedding` 适用于图文混合检索；`qwen3-rerank` 支持最多 500 文档的纯文本重排序 [原文标题](../../raw/model-user-guide/model-experience/embedding-rerank-model.md)。
|
||||
|
||||
> **注意**：文档 1 与文档 2 均将 `qwen3.7-plus` 列为视觉理解首选，但文档 2 明确其支持“最长2小时视频”，而文档 1 未提及视频能力——该差异源于文档 1 聚焦纯文本生成场景，视觉能力属文档 2 范畴，非矛盾，而是模块化分工体现。
|
||||
> **注意**：文档 1 中称 `qwen3.7-max` “不支持结构化输出”，但文档 2 的表格明确列出 `qwen3.7-plus` 和 `qwen3.7-flash` 均支持结构化输出，而 `qwen3.7-max` 对应列为“不支持”。该差异非矛盾，而是功能设计差异——`qwen3.7-max` 定位强推理，牺牲部分生成稳定性以换取逻辑深度，此行为符合其产品定位。
|
||||
|
||||
## 关键参数
|
||||
|
||||
各模型系列通过标准化参数控制行为，核心参数如下：
|
||||
各模态模型共性参数与典型取值如下：
|
||||
|
||||
- **上下文长度**：文本模型如 `qwen3.7-plus` 固定为 1M [Token](../concepts/token.md)；视觉模型同样继承该上下文，但实际消耗受图像分辨率影响（公式：`h × w / (32 × 32) + 2`）；`qwen-long` 独立支持 10M [Token](../concepts/token.md)。
|
||||
- **思考模式**：通过 `enable_thinking`（Responses API）或 `reasoning.effort` 控制，所有 Qwen3+ 模型均支持，但 `qwen-long` 和 `qwen3-vl-*` 系列明确标注“不支持”。
|
||||
- **结构化输出**：需在请求中声明 `response_format: { "type": "json_object" }`，仅 `qwen3.7-plus`、`qwen3.7-flash` 等部分模型原生支持，`qwen3.7-max` 明确标注“不支持” [原文标题](../../raw/model-user-guide/model-experience/text-generation-model.md)。
|
||||
- **多模态输入字段**：视觉/全模态模型通过 `input.image`、`input.images`、`input.video` 区分输入类型；Tripo 3D 模型严格互斥 `prompt`/`image`/`images` 字段 [原文标题](../../raw/model-user-guide/model-experience/tripo-3d-generation-guide.md)。
|
||||
- **音频处理参数**：ASR 模型通过 `hotword`（Fun-ASR）或 `system_prompt`（Qwen3.5-Omni）增强专业术语识别；TTS 模型通过 `format`（`mp3`/`wav`）和 `gender`（`male`/`female`）控制输出；S2S 模型通过 `is_instrumental=true` 生成纯音乐。
|
||||
| 参数名 | 说明 | 典型取值/约束 | 来源 |
|
||||
|--------|------|----------------|------|
|
||||
| `model` | 模型 ID，必须精确匹配（含快照版本） | `qwen3.7-plus`, `wan2.7-image-pro`, `fun-music-v1` | 全部文档 |
|
||||
| `input` | 输入内容载体，结构因模态而异 | 文本：`{"prompt": "..."}`；图像：`{"image": "url"}`；音频：`{"audio_url": "..."}`；3D：`{"prompt": "...", "images": [...]}` | [原文标题](../../raw/model-user-guide/model-experience/tripo-3d-generation-guide.md) |
|
||||
| `parameters` | 模型特有配置 | `texture_quality: "standard"`（Tripo）、`format: "mp3"`（Fun-Music）、`reasoning.effort: "medium"`（Qwen 思考模式） | 全部文档 |
|
||||
| `X-DashScope-Async` | 异步任务必需 Header | `"enable"`（Tripo、Fun-Music 等长耗时任务） | [原文标题](../../raw/model-user-guide/model-experience/tripo-3d-generation-guide.md) |
|
||||
| `Authorization` | 认证凭证 | `Bearer $DASHSCOPE_API_KEY`，需提前配置环境变量或显式传入 | 全部文档 |
|
||||
|
||||
> **注意**：文档 10 与文档 11 均指出 `qwen3.5-omni-plus-realtime` 支持联网搜索，但文档 10 明确标注“联网搜索与 Function Calling 不可同时开启”，而文档 11 未提及此互斥限制。实际调用中必须遵守该约束，否则请求将失败。
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **API 接入**：统一使用 DashScope SDK 或 HTTP/WebSocket 直调。所有模型需配置 `DASHSCOPE_API_KEY` 及 `{WorkspaceId}`（华北2地域专属），Tripo 3D 模型强制要求北京地域 [原文标题](../../raw/model-user-guide/model-experience/tripo-3d-generation-guide.md)。
|
||||
- **[异步任务](../concepts/asynchronous-task.md)**：Tripo 3D、视频生成等耗时操作必须启用 `X-DashScope-Async: enable` 头，并轮询 `task_id` 获取结果（有效期 24 小时）。
|
||||
- **[流式输出](../concepts/streaming-output.md)**：WebSocket 接口（如 `qwen-audio-3.0-realtime-plus`、`fun-asr-realtime`）支持音频/文本流式传输；HTTP 接口（如 `qwen3.5-omni-plus`）支持 `stream=true` 流式响应。
|
||||
- **文件上传**：ASR/TTS/S2S 文件模式需通过 `multipart/form-data` 提交音频，或传入公网可访问 URL；Tripo 3D 的 `images` 字段要求传入 URL 列表（2–4 张，JPEG/PNG，≤20MB）。
|
||||
统一采用 RESTful API 调用，遵循以下通用流程：
|
||||
|
||||
1. **准备凭证**：获取 API Key 并配置至环境变量 `DASHSCOPE_API_KEY` 或请求头；
|
||||
2. **构造请求**：
|
||||
- HTTP 模式：`POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/{service}/{endpoint}`；
|
||||
- WebSocket 模式：连接 `wss://dashscope.aliyuncs.com/api/v1/services/{service}/{endpoint}`；
|
||||
3. **提交输入**：按模型要求组织 `input` 字段（如文本、URL、base64、文件 token）；
|
||||
4. **处理响应**：
|
||||
- 同步接口：直接返回结果（如 TTS 音频 URL、ASR 文本）；
|
||||
- 异步接口（Tripo、Fun-Music）：先获 `task_id`，再轮询 `GET /api/v1/tasks/{task_id}` 获取 `SUCCEEDED` 状态及产物 URL；
|
||||
- 流式接口（Realtime ASR/TTS）：建立 WebSocket 连接后，接收分块数据帧。
|
||||
|
||||
所有模型均需指定 `WorkspaceId`（业务空间 ID），且多数服务（Tripo、Fun-Music、Fun-ASR）仅在华北2（北京）地域可用。跨地域调用需确认模型是否在目标 Region 发布（如文档 1 中列出的新加坡/美国/法兰克福链接）。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域限制**：Tripo 3D 模型仅限华北2（北京）地域；Fun-Music 邀测阶段亦限定北京地域；部分模型（如 `wan2.6-t2v-us`）明确标注“适用于美国部署范围”。
|
||||
- **能力冲突**：Qwen3.5-Omni 的联网搜索与 Function Calling **不可同时开启**；思考模式启用时，S2S 模型 **不支持生成语音输出**；`qwen3.7-max` 不支持结构化 JSON 输出，与 `qwen3.7-plus` 形成能力取舍。
|
||||
- **版本兼容性**：`text-embedding-v3` 与 `v4` 维度不兼容，迁移需重建索引；旧版模型（如 `qwen2.5-omni-7b`、`qwen-omni-turbo`）已停止更新，新项目应避免选用 [原文标题](../../raw/model-user-guide/model-experience/omni.md)。
|
||||
- **资源约束**：视频生成最大时长为 15 秒（`happyhorse-1.1-t2v`），Tripo 3D 多图输入限 4 张；Fun-ASR 非实时模型支持单文件最长 12 小时/2GB，而 Qwen3.5-Omni 限 3 小时/2GB。
|
||||
- **计费差异**：Qwen-TTS 旧版按 Token 计费，Qwen3-TTS 系列改为按请求/时长计费；Tripo 3D 按任务计费，H3.1 模型成本高于 P1.0。
|
||||
- **地域限制**：Tripo 3D、Fun-Music、Fun-ASR 等模型**仅支持华北2（北京）**，调用前必须确认 Endpoint 域名含 `cn-beijing`；其他模型（如 Qwen3 系列）在多 Region 可用，但需通过控制台确认具体部署状态 [原文标题](../../raw/model-user-guide/model-experience/tripo-3d-generation-guide.md)。
|
||||
- **输入规格**：
|
||||
- 图像：单图最高 1600 万像素，[Token](../concepts/token.md) 消耗 = `h × w / (32 × 32) + 2`；
|
||||
- 视频：`qwen3.7-plus` 支持最长 2 小时/2GB，`qwen3-vl-plus` 限 1 小时；
|
||||
- 音频：Fun-ASR 非实时最大 12 小时/2GB，Qwen3.5-Omni 非实时限 3 小时/2GB；
|
||||
- 3D 多图输入：仅接受 2–4 张 JPEG/PNG，单图 ≤ 20MB；
|
||||
- **功能互斥**：
|
||||
- `qwen3.5-omni-plus` 的联网搜索与 Function Calling 不可同时启用；
|
||||
- `qwen3-omni-flash` 的思考模式启用时**不生成语音输出**（仅文本）；
|
||||
- **版本管理**：快照版本（如 `qwen3.7-plus-2026-05-26`）提供确定性行为，但需主动维护；`-latest` 或无后缀版本自动更新，适合快速迭代但需监控变更日志。
|
||||
|
||||
## 来源文档
|
||||
|
||||
@@ -46,12 +63,12 @@
|
||||
- [视觉理解](../../raw/model-user-guide/model-experience/vision-model.md)
|
||||
- [图片生成与编辑](../../raw/model-user-guide/model-experience/image-model.md)
|
||||
- [视频生成与编辑](../../raw/model-user-guide/model-experience/video-generate-edit-model.md)
|
||||
- [语音合成](../../raw/model-user-guide/model-experience/tts-model.md)
|
||||
- [Tripo 3D模型生成](../../raw/model-user-guide/model-experience/tripo-3d-generation-guide.md)
|
||||
- [语音识别](../../raw/model-user-guide/model-experience/asr-model.md)
|
||||
- [语音合成](../../raw/model-user-guide/model-experience/tts-model.md)
|
||||
- [音乐生成](../../raw/model-user-guide/model-experience/fun-music.md)
|
||||
- [语音转语音](../../raw/model-user-guide/model-experience/s2s-model.md)
|
||||
- [语音识别](../../raw/model-user-guide/model-experience/asr-model.md)
|
||||
- [向量与重排序](../../raw/model-user-guide/model-experience/embedding-rerank-model.md)
|
||||
- [全模态](../../raw/model-user-guide/model-experience/omni.md)
|
||||
- [语音转语音](../../raw/model-user-guide/model-experience/s2s-model.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,54 +1,52 @@
|
||||
# model high speed inference
|
||||
|
||||
百炼平台提供两种面向高吞吐、低延迟场景的推理加速能力：**TPM 预留（[Token](../concepts/token.md) Per Minute Reservation）** 和 **快速模式（Fast Mode）**。前者通过预付费锁定专属容量保障稳定性，后者通过优化调度与计算路径提升单位时间输出吞吐量（TPS）。二者可独立使用，也可组合（如在 TPM 预留实例上启用 fast-preview 模型），适用于对响应速度、确定性 SLA 或成本敏感度有不同侧重的生产场景。
|
||||
百炼平台提供两种面向高吞吐、低延迟场景的推理加速能力：TPM 预留（保障专属容量）与快速模式（提升单请求输出速度）。二者定位不同——TPM 预留解决**容量确定性问题**（避免公共池限流），快速模式解决**单次响应时效性问题**（提升 TPS 与首 token 延迟）。开发者需根据业务 SLA（如是否容忍 429、是否要求 <500ms 首 token）选择组合使用。两者均通过替换 `model` 参数接入，无需修改 SDK 或协议。
|
||||
|
||||
## 支持的模型与功能
|
||||
## 支持的模型/功能
|
||||
|
||||
- **TPM 预留**：为指定模型提供刚性容量保障，支持千问（Qwen）、GLM、DeepSeek、Kimi 等主流模型的多个版本（如 `qwen3.7-max-2026-05-20`、`glm-5.2`、`deepseek-v4-pro` 等），覆盖华北2（北京）和新加坡地域。详情见 [TPM 预留](../../raw/model-user-guide/model-high-speed-inference/tpm-reservation.md)。
|
||||
- **快速模式**：当前仅支持 `glm-5.2-fast-preview` 模型（北京/新加坡双地域），处于 preview 阶段，提供 1.5~2 倍于标准 API 的 TPS（最高达 80~100 TPS），并支持[流式输出](../concepts/streaming-output.md)中的 `reasoning_content` 分离推送。详情见 [快速模式](../../raw/model-user-guide/model-high-speed-inference/fast-mode.md)。
|
||||
- > **注意**：两文档中对 `glm-5.2` 的缓存折扣描述存在差异——[TPM 预留](../../raw/model-user-guide/model-high-speed-inference/tpm-reservation.md) 明确其缓存命中部分按 25% 折算容量；而 [快速模式](../../raw/model-user-guide/model-high-speed-inference/fast-mode.md) 表格中标注“缓存命中”为 `4元`（疑似误标为单价），实际缓存机制应以 [TPM 预留](../../raw/model-user-guide/model-high-speed-inference/tpm-reservation.md) 文档为准，快速模式继承基础模型的缓存能力但未额外调整折扣率。
|
||||
- **TPM 预留**：为指定模型锁定专属输入/输出吞吐量（单位：kTPM），支持千问、GLM、DeepSeek、Kimi 等主流模型，覆盖华北2（北京）和新加坡地域。详情见 [TPM 预留](../../raw/model-user-guide/model-high-speed-inference/tpm-reservation.md)。
|
||||
- **快速模式**：当前仅支持 `glm-5.2-fast-preview` 模型（北京、新加坡双地域），提供 1.5~2 倍于标准 API 的 TPS（达 80~100 TPS），适用于 AI 编程助手、Agent 多步推理等对输出速度敏感的场景。详情见 [快速模式](../../raw/model-user-guide/model-high-speed-inference/fast-mode.md)。
|
||||
- > **注意**：两文档对 `glm-5.2` 的缓存折扣描述存在差异。[TPM 预留](../../raw/model-user-guide/model-high-speed-inference/tpm-reservation.md) 明确其缓存折扣为 0.25；而 [快速模式](../../raw/model-user-guide/model-high-speed-inference/fast-mode.md) 在计费表中单独列出“缓存命中”单价（4元/百万[Token](../concepts/token.md)），未说明是否复用相同缓存机制。实际调用时请以控制台最新参数或 `usage.prompt_tokens_details.cached_tokens` 字段为准。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | TPM 预留 | 快速模式 |
|
||||
|------|----------|-----------|
|
||||
| **核心指标** | 输入/输出 kTPM（1 kTPM = 1,000 tokens/min） | TPS（tokens per second），实测 80~100 |
|
||||
| **计费单位** | 预付费（按天，kTPM × 天数） + 溢出按量 | 按 token 计费（输入/输出单价独立，与标准 API 一致） |
|
||||
| **容量保障** | 专属、刚性兑付（不共享） | 无专属容量，依赖公共资源池 + 排队缓冲 |
|
||||
| **溢出行为** | 可选：自动降级至按量（默认）或返回 429 | 请求进入排队队列，不立即限流 |
|
||||
| **缓存支持** | 支持（各模型有明确缓存折扣率与阶梯系数） | 继承基础模型缓存能力（如 `glm-5.2-fast-preview` 对应 `glm-5.2` 的 25% 缓存折扣） |
|
||||
| **核心标识** | 专属模型 code（如 `qwen3.7-max-2026-05-20-tpm-xxxxx`），由控制台生成 | 固定 model ID（`glm-5.2-fast-preview`） |
|
||||
| **容量单位** | 输入/输出 kTPM（1 kTPM = 1,000 tokens/分钟） | 无独立容量单位，按 token 计费，但受全局 TPM 配额排队约束 |
|
||||
| **溢出行为** | 可选：自动溢出至按量计费（默认）或返回 429 | 请求进入排队队列，不立即限流（[快速模式](../../raw/model-user-guide/model-high-speed-inference/fast-mode.md)） |
|
||||
| **缓存支持** | 支持（如 GLM-5.2 缓存命中部分按 25% 折算容量） | 支持（计费表中单独列出缓存命中单价） |
|
||||
| **长输入阶梯** | 部分模型支持（如 GLM-5.1 在 [32K,200K] 区间输入系数 1.33） | 文档未提及阶梯系数，按标准 token 计费 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **TPM 预留**：
|
||||
1. 在控制台创建预留实例，获取专属 `model` code（如 `tpm-qwen37max-abc123`）；
|
||||
2. 将 API 请求中的 `model` 字段替换为该 code；
|
||||
3. 调用域名与标准 API 一致（`https://dashscope.aliyuncs.com/...`）。详见 [TPM 预留](../../raw/model-user-guide/model-high-speed-inference/tpm-reservation.md) 中的「创建 TPM 预留」与「API 接入」章节。
|
||||
1. 在百炼控制台创建预留实例，获取专属模型 code；
|
||||
2. 将 API 请求中的 `model` 替换为该 code；
|
||||
3. 调用域名与标准 API 一致（`https://dashscope.aliyuncs.com/...`）。示例见 [TPM 预留](../../raw/model-user-guide/model-high-speed-inference/tpm-reservation.md) 中的 Python/curl 代码片段。
|
||||
|
||||
- **快速模式**：
|
||||
1. 直接使用 fast-preview 模型 ID（如 `glm-5.2-fast-preview`）作为 `model` 参数；
|
||||
2. **必须使用专属接入域名**：`https://{workspace_id}.{region}.maas.aliyuncs.com/compatible-mode/v1`（region 如 `cn-beijing`）；
|
||||
3. workspace_id 需在业务空间管理页面切换地域后查看。示例见 [快速模式](../../raw/model-user-guide/model-high-speed-inference/fast-mode.md) 中的 curl 与 Python 调用片段。
|
||||
1. 使用 `glm-5.2-fast-preview` 作为 `model` 参数；
|
||||
2. **必须使用专属域名**：`https://{workspace_id}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`（北京）或对应新加坡地域域名；
|
||||
3. 支持流式响应，`reasoning_content` 与 `content` 分离推送。完整示例见 [快速模式](../../raw/model-user-guide/model-high-speed-inference/fast-mode.md)。
|
||||
|
||||
- > **注意**：快速模式 preview 版本不支持与 TPM 预留的专属 model code 混用——即不能将 `tpm-glm52-xxx` 作为 `glm-5.2-fast-preview` 的前缀。若需同时享受容量保障与高速输出，须为 `glm-5.2-fast-preview` 单独购买 TPM 预留（当前控制台暂未开放该模型的 TPM 预留入口，属能力缺口，建议关注后续更新）。
|
||||
- > **注意**：快速模式为 preview 阶段，[快速模式](../../raw/model-user-guide/model-high-speed-inference/fast-mode.md) 明确提示“能力与规格可能随版本调整”，生产环境使用前需评估兼容性风险。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **TPM 预留**：
|
||||
- 创建后需等待实例状态变为「运行中」方可调用；
|
||||
- 短时流量激增需预热（可能引发短暂延迟波动），建议实现客户端重试与排队；
|
||||
- 退订后专属 model code 立即失效，请求回退至公共资源；
|
||||
- 缩容/退订按 1.5 倍系数结算已用费用（见 [TPM 预留](../../raw/model-user-guide/model-high-speed-inference/tpm-reservation.md) 计费说明）。
|
||||
- 创建后需等待实例状态变为“运行中”方可调用；
|
||||
- 短时间内请求量快速拉升需预热，预热期间可能出现延迟波动，建议实现请求排队或重试机制（见 [TPM 预留](../../raw/model-user-guide/model-high-speed-inference/tpm-reservation.md)）；
|
||||
- 服务到期后 2 小时内仍可调用，但 14 小时后实例删除不可恢复。
|
||||
|
||||
- **快速模式**：
|
||||
- 仅 preview 阶段，模型列表、性能指标与接口行为可能调整，不承诺长期兼容；
|
||||
- 不支持所有标准 API 参数（如部分采样参数可能被忽略），以实际返回结果为准；
|
||||
- 流式响应中 `reasoning_content` 与 `content` 字段分离推送，客户端需分别处理；
|
||||
- 错误码体系与标准 API 一致，但排队超时等新场景可能引入额外错误类型（参见 [快速模式](../../raw/model-user-guide/model-high-speed-inference/fast-mode.md) 错误码文档）。
|
||||
- 仅限 `glm-5.2-fast-preview`，不支持其他模型；
|
||||
- 不支持 `stream=false` 下的 `reasoning_content` 字段（仅流式返回）；
|
||||
- 返回结构中 `usage.completion_tokens_details.reasoning_tokens` 字段统计思考 token，计入总输出 token 计费。
|
||||
|
||||
- **共性限制**：
|
||||
- 两类能力均不改变模型本身的能力边界（如上下文长度、多模态支持等），仅优化推理调度与资源供给；
|
||||
- TPM 预留与快速模式不可跨地域复用（北京预留不适用于新加坡 endpoint，反之亦然）。
|
||||
- 两者均不改变模型本身能力（如上下文长度、[多模态](../concepts/multi-modal.md)支持），仅优化调度与资源分配；
|
||||
- TPM 预留与快速模式**不可叠加使用**：`glm-5.2-fast-preview` 不支持 TPM 预留，TPM 预留的模型 code 也不支持快速模式协议。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,51 +1,72 @@
|
||||
# model monitoring
|
||||
|
||||
模型监控（Model Monitoring）是百炼平台提供的核心可观测性能力，用于实时追踪模型调用行为、性能指标、成本消耗及异常事件。它面向生产环境提供细粒度的调用日志、多维指标监控与主动告警能力，帮助开发者及时发现服务降级、成本突增或内容安全风险。该功能覆盖所有已上线模型，但高级能力（如分钟级延迟日志、TPS指标、Grafana接入）受地域与配置状态限制。
|
||||
模型监控是百炼平台提供的核心可观测性能力，用于实时跟踪模型调用行为、性能指标与资源消耗。它支持从宏观用量统计到单次请求级日志的全链路观测，并可基于关键指标（如失败率、首[Token](../concepts/token.md)延时、TPM）配置主动告警。该功能面向生产环境稳定性保障与成本精细化治理，不依赖应用层埋点，数据由平台自动采集。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **基础监控**：支持[选择模型](https://help.aliyun.com/zh/model-studio/models)中的全部模型（含调优后的自定义模型），覆盖所有地域；数据延迟为小时级（高峰期可达1–2小时）[原文标题](../../raw/model-user-guide/model-monitoring/model-telemetry.md)。
|
||||
- **高级监控**：仅限北京、上海、新加坡、弗吉尼亚地域下的模型，提供分钟级日志、TPS（`model_tps_per_request`）等深度指标，并支持Prometheus API对接 [原文标题](../../raw/model-user-guide/model-monitoring/model-telemetry.md)。
|
||||
- **告警能力**：仅在北京、新加坡、弗吉尼亚地域可用，支持对失败率、首[Token](../concepts/token.md)延时、[Token](../concepts/token.md)消耗等指标设置多级告警 [原文标题](../../raw/model-user-guide/model-monitoring/model-telemetry.md)。
|
||||
- **日志回溯**：仅部分模型支持请求/响应内容记录（如 `qwen3-plus`、`qwen-flash` 等快照版本），且**仅在开通推理日志后生效**，历史调用无法补录；不支持的模型界面会明确提示“当前模型暂不支持日志”。
|
||||
- **监控覆盖范围**：
|
||||
- 普通监控支持[所有在模型列表中可选的模型](../../raw/model-user-guide/model-monitoring/model-usage-statistics.md)，包括基于它们调优后的自定义模型；
|
||||
- 高级监控（含分钟级延迟、TPS、推理日志等）仅支持北京、上海、新加坡、弗吉尼亚地域下的模型；
|
||||
- 告警功能仅支持北京、新加坡、弗吉尼亚地域下的模型。
|
||||
|
||||
> **注意**：文档1中称“模型列表中的所有模型均支持查看用量”，而文档2明确指出日志与高级指标存在地域和模型版本限制。二者不矛盾——“用量统计”（文档1）指聚合计费数据，属基础能力；“模型监控”（文档2）指实时可观测性能力，需额外开通且有范围约束。实际使用中应以[模型监控](../../raw/model-user-guide/model-monitoring/model-telemetry.md)文档为准判断功能可用性。
|
||||
- **核心功能模块**：
|
||||
- **调用记录追踪**：支持按 Request ID 查看单次调用的输入、输出、状态码、耗时及 [Token](../concepts/token.md) 用量；
|
||||
- **多维指标监控**：涵盖安全（内容安全错误次数）、成本（平均单次请求调用量）、性能（RPM、TPM、调用时长、首[Token](../concepts/token.md)延时、非首Token延时）、错误（失败率、限流错误次数）四大类；
|
||||
- **历史对话审计**：仅对已开通推理日志且模型明确支持的版本（如 `qwen3-plus-2025-12-01` 及之后快照）生效；
|
||||
- **Grafana / 自建系统集成**：通过私有 Prometheus HTTP API 提供标准指标查询能力，详见 [模型监控 (raw/model-user-guide/model-monitoring/model-telemetry.md)](../../raw/model-user-guide/model-monitoring/model-telemetry.md)。
|
||||
|
||||
> **注意**：文档1中称“模型用量页面数据延迟约为 1 小时”，而文档2明确区分普通监控（小时级）与高级监控（分钟级）——二者不矛盾，但需注意：**普通监控不提供首Token延时、TPS、单次请求日志等高级能力**，这些仅在开通高级监控后可用。开发者应依据 SLA 要求选择对应能力层级。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 说明 | 来源 |
|
||||
|------|------|------|
|
||||
| `workspace_id` | 业务空间ID，用于按空间维度隔离监控数据，必填过滤条件 | [原文标题](../../raw/model-user-guide/model-monitoring/model-telemetry.md) |
|
||||
| `model` | 模型Code（如 `qwen-plus`），用于精确筛选单个模型指标 | [原文标题](../../raw/model-user-guide/model-monitoring/model-telemetry.md) |
|
||||
| `apikey_id` | API Key ID（非密钥本身），用于归因调用来源；值为 `-1` 表示来自控制台调用 | [原文标题](../../raw/model-user-guide/model-monitoring/model-telemetry.md) |
|
||||
| `protocol` / `sub_protocol` | 协议类型（HTTP/SSE/WS）与子协议（DEFAULT/ASYNC），影响延时与吞吐分析维度 | [原文标题](../../raw/model-user-guide/model-monitoring/model-telemetry.md) |
|
||||
| `max_tokens` | 调用API时显式设置，直接影响输出[Token](../concepts/token.md)数与费用，建议在生产中强制设限 | [原文标题](../../raw/model-user-guide/model-monitoring/model-usage-statistics.md) |
|
||||
| 参数 | 说明 | 来源约束 |
|
||||
|------|------|----------|
|
||||
| `workspace_id` | 业务空间 ID，为监控数据隔离与筛选的关键 Label | 必填（Prometheus 查询中需显式指定） |
|
||||
| `model` | 模型 Code（如 `qwen-plus`），区分大小写 | 必填（Prometheus 查询中需显式指定） |
|
||||
| `apikey_id` | API Key ID（非密钥本身），值为 `-1` 表示控制台调用 | 可选，用于按密钥维度归因 |
|
||||
| `protocol` / `sub_protocol` | 协议类型（HTTP/SSE/WS）与子协议（DEFAULT/ASYNC） | 影响性能分析粒度，异步调用常见于图像生成等场景 |
|
||||
| `step` | Prometheus 查询时间步长，最小支持 `60s`（即分钟级） | 高级监控下有效；普通监控无此参数暴露 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **启用监控**
|
||||
- 进入目标业务空间的[模型监控](https://bailian.console.aliyun.com/?tab=model#/model-telemetry)页面 → 点击右上角「模型监控配置」→ 开通**审计日志**与**推理日志**（高级监控必需）。
|
||||
- 高级监控开通后，方可使用分钟级日志、TPS指标及Prometheus API。
|
||||
1. **基础监控查看**：
|
||||
进入 [模型监控](https://bailian.console.aliyun.com/?tab=model#/model-telemetry) 页面，系统自动列出当前业务空间内所有已调用模型。点击某行「监控」可查看调用统计（失败详情、Token 消耗趋势）与性能指标（RPM、TPM、延时分布）；点击「日志」可查看已开通推理日志的调用记录。
|
||||
|
||||
2. **查看指标**
|
||||
- 在「模型监控」列表点击目标模型的「监控」，切换至「调用统计」或「性能指标」页签，支持按API Key、推理类型（实时/批量）、时间范围（最大30天）筛选。
|
||||
- Token消耗可在「调用量」区域直接查看；单次调用明细（含输入/输出）需进入「日志」页签（仅支持模型见文档2列表）。
|
||||
2. **开通高级能力**：
|
||||
在目标业务空间的模型监控页右上角点击「模型监控配置」，依次开通：
|
||||
- 审计日志（用于操作审计）
|
||||
- 推理日志（用于请求/响应内容记录，**必须开通才可查看单次 Token 用量与对话内容**）
|
||||
> 开通后数据同步存在分钟级延迟，历史调用无法补录 —— 此限制在 [模型监控 (raw/model-user-guide/model-monitoring/model-telemetry.md)](../../raw/model-user-guide/model-monitoring/model-telemetry.md) 中明确强调。
|
||||
|
||||
3. **配置告警**
|
||||
- 进入[模型告警](https://bailian.console.aliyun.com/?tab=model#/model-alert)页面 → 「创建告警规则」→ 选择模型、指标模板（如“Token消耗突增”）、阈值与通知渠道（短信/钉钉/Webhook等）。
|
||||
3. **创建告警规则**：
|
||||
进入 [模型告警](https://bailian.console.aliyun.com/?tab=model#/model-alert) 页面，点击「创建告警规则」，选择模型、监控模板（如“失败率突增”、“TPM超阈值”）并配置通知渠道（短信/邮件/钉钉机器人/Webhook）。告警等级（INFO/ WARNING/ ERROR/ CRITICAL）决定通知方式组合。
|
||||
|
||||
4. **对接自建系统**
|
||||
- 获取Prometheus HTTP API地址（通过「模型监控配置」→「云监控Prometheus实例」→「查看详情」）。
|
||||
- 使用标准PromQL查询，例如：
|
||||
`GET {API}/api/v1/query_range?query=model_usage{workspace_id="xxx",model="qwen-plus"}&start=...&step=60s`
|
||||
4. **对接自建系统**：
|
||||
获取 Prometheus HTTP API 地址后，使用标准 PromQL 查询，例如：
|
||||
```http
|
||||
GET {API}/api/v1/query_range?query=model_usage{workspace_id="llm-xxx",model="qwen-plus"}&start=2025-11-20T00:00:00Z&end=2025-11-20T23:59:59Z&step=60s
|
||||
```
|
||||
认证需提供 Base64 编码的 `AccessKey:AccessKeySecret`，且 AKSK 必须与 Prometheus 实例归属同一账号 —— 具体参数与指标清单见 [模型监控 (raw/model-user-guide/model-monitoring/model-telemetry.md)](../../raw/model-user-guide/model-monitoring/model-telemetry.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **数据时效性**：普通监控（用量汇总）延迟约1小时；推理日志延迟为分钟级，但需等待日志开通后首次调用完成才开始采集。
|
||||
- **地域限制**：高级监控、告警、日志回溯功能**仅限北京、新加坡、弗吉尼亚地域**；上海地域仅支持基础监控（无TPS、无分钟级日志）。
|
||||
- **模型兼容性**：并非所有模型支持请求/响应内容记录，具体支持列表以[模型监控](../../raw/model-user-guide/model-monitoring/model-telemetry.md)文档为准；不支持时界面明确提示。
|
||||
- **免费额度联动**：监控本身不消耗免费额度，但用量统计与免费额度使用情况强关联；开启「免费额度用完即停」后，额度耗尽将返回403错误，此时监控仍可查看历史数据，但新调用被阻断 [原文标题](../../raw/model-user-guide/model-monitoring/model-usage-statistics.md)。
|
||||
- **批量操作风险**：在「免费额度」页面进行批量开关操作时，若账号未绑定有效支付方式，操作将失败并提示绑定银行卡，需提前校验支付状态。
|
||||
- **地域与模型支持限制**：
|
||||
- 推理日志（含请求/响应内容）**仅支持北京、新加坡、弗吉尼亚地域**，且仅限文档2中明确列出的模型快照版本（如 `qwen3.7-plus-2026-05-26`）；未列明的模型或旧快照版本即使开通日志也无法记录内容。
|
||||
- 上海地域虽支持高级监控，但**不支持推理日志**（文档2未提上海支持日志，仅列北京/新加坡/弗吉尼亚）。
|
||||
|
||||
- **数据时效性**：
|
||||
- 普通监控（用量汇总、失败率等）延迟为 **1–2 小时**；
|
||||
- 高级监控（推理日志、TPS、首Token延时）延迟为 **分钟级**；
|
||||
- 免费额度数据在控制台**分钟级更新**，但账单中免费额度消耗记录按分钟汇总生成，存在轻微滞后。
|
||||
|
||||
- **权限与范围**：
|
||||
- 子业务空间成员**仅能查看本空间数据**，无法跨空间筛选；
|
||||
- 主账号可查看全部空间，但告警规则需在**目标业务空间内单独创建**；
|
||||
- 开通推理日志需主账号或具备 `AliyunBaiLianFullAccess` 权限的 RAM 用户。
|
||||
|
||||
- **成本与计费**：
|
||||
- 高级监控（含推理日志、TPS指标、Prometheus接入）为**收费功能**，具体资费以控制台报价为准；
|
||||
- 免费额度用完即停功能开启后，若额度耗尽将返回 `403 AllocationQuota.FreeTierOnly` 错误 —— 此行为在 [模型用量 (raw/model-user-guide/model-monitoring/model-usage-statistics.md)](../../raw/model-user-guide/model-monitoring/model-usage-statistics.md) 中明确定义，开发者需在监控中重点告警该错误码。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,47 +1,50 @@
|
||||
# plug in
|
||||
|
||||
[插件](../concepts/plugin.md)是百炼平台用于扩展大模型能力的核心机制，通过将外部工具（API）集成到大模型应用中，弥补其在实时信息获取、精确计算、代码执行、图像生成等场景下的固有局限。[插件](../concepts/plugin.md)以“工具集合”形式组织，支持官方预置、三方市场及完全自定义三种类型，可被智能体、工作流或 Assistant API 主动调用或编排执行。所有[插件](../concepts/plugin.md)均需显式授权与配置后方可使用。
|
||||
插件是百炼平台用于扩展大模型能力的核心机制，通过将外部工具（API）集成到大模型应用中，弥补其在实时信息获取、精确计算、代码执行、图像生成等方面的固有局限。插件以“工具集合”形式组织，支持官方预置、三方市场及完全自定义三种类型，可被智能体应用、工作流应用或 Assistant API 主动调用或编排执行。所有插件均需经服务关联角色（`AliyunServiceRoleForSFMAccessCloudAPI`）授权后方可使用。
|
||||
|
||||
## 支持的模型/功能
|
||||
## 支持的模型与功能
|
||||
|
||||
当前插件能力仅在以下模型上可用：`qwen-turbo`、`qwen-plus`、`qwen-max`、`qwen-vl-max` 和 `qwen-vl-plus`。各模型对插件的兼容性存在差异，实际调用效果请以控制台运行结果为准 [插件概述](../../raw/application-user-guide/plug-in/plug-in-overview.md)。
|
||||
插件按来源分为三类：
|
||||
- **官方插件**：组件广场预置，开箱即用，无需参数配置，包括 `code_interpreter`（Python 执行）、`calculator`（数学计算）、`text_to_image`（文生图）、`quark_search`（实时搜索）、`generate_qrcode`（二维码生成）、`github_search`（GitHub 项目检索）等 [官方和第三方插件](../../raw/application-user-guide/plug-in/plugins.md)。
|
||||
- **三方插件**：来自阿里云云市场，覆盖商业服务、教育、图像视频等领域，需开通后使用。
|
||||
- **自定义插件**：用户自主创建或从云市场导入，支持完整 API 接入、鉴权（Header/Query，含 basic/bearer/appcode 类型）、输入输出参数定义及高级示例配置 [自定义插件](../../raw/application-user-guide/plug-in/custom-plug-ins.md)。
|
||||
百炼当前支持在以下模型上启用插件能力：`qwen-turbo`、`qwen-plus`、`qwen-max`、`qwen-vl-max` 和 `qwen-vl-plus`。各模型对插件的兼容性存在差异，实际可用性请以控制台运行结果为准 [插件概述](../../raw/application-user-guide/plug-in/plug-in-overview.md)。
|
||||
|
||||
> **注意**：文档 1 与文档 2 均列出 `quark_search` 插件，但文档 2 明确指出其“目前支持检索出网页标题、关键词和摘要，但不支持直接访问网页详情”，而文档 1 仅简述为“查找公开的网络知识和信息”。应以文档 2 的限定说明为准，避免误判插件能力边界。
|
||||
官方插件提供开箱即用的常用能力，包括：
|
||||
- `code_interpreter`：执行 Python 代码（支持 `matplotlib`、`pandas`、`sympy` 等依赖，**不支持网络访问与本地文件上传**）；
|
||||
- `calculator`：高精度数学运算；
|
||||
- `text_to_image`：文生图（限时免费，需申请开通）；
|
||||
- `quark_search`：实时网络搜索（返回标题、关键词、摘要，**不支持网页详情访问**）；
|
||||
- `generate_qrcode`：URL 转二维码；
|
||||
- `github_search`：GitHub 项目检索（返回标题、链接、摘要，**不支持项目详情访问**）。
|
||||
|
||||
三方插件覆盖商业服务、图像视频、教育等场景，需在云市场开通后调用；自定义插件支持通过 REST API 接入任意业务系统，需明确定义工具路径、输入/输出参数及鉴权方式 [自定义插件](../../raw/application-user-guide/plug-in/custom-plug-ins.md)。
|
||||
|
||||
> **注意**：文档 1 与文档 2 均列出 `quark_search` 插件限制为“不支持直接访问网页详情”，但文档 2 在常见问题中补充说明“联网搜索（`enable_search`）也是基于夸克搜索”，暗示二者底层一致；而文档 1 未提及 `enable_search`。开发者应以 `quark_search` 插件显式调用为准，避免混淆 `enable_search` 这一旧版开关行为 [官方和第三方插件](../../raw/application-user-guide/plug-in/plugins.md)。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **工具 ID**：唯一标识插件下的具体工具（如 `calculator`），API 调用时必需。可通过插件详情页悬浮图标复制 [官方和第三方插件](../../raw/application-user-guide/plug-in/plugins.md)。
|
||||
- **插件 URL 与工具路径**：自定义插件中，`插件URL`（如 `https://example.com`）为域名根地址，`工具路径`（如 `/query`）为其相对路径，二者拼接构成完整调用地址 [自定义插件](../../raw/application-user-guide/plug-in/custom-plug-ins.md)。
|
||||
- **工具 ID**：唯一标识插件下的具体工具（如 `calculator`），API 调用时必需。可通过插件详情页悬浮图标复制获取。
|
||||
- **插件 URL 与工具路径**：自定义插件中，`插件URL`（如 `https://example.com`）与 `工具路径`（如 `/query`）拼接构成完整请求地址。
|
||||
- **输入参数配置**：
|
||||
- `传参方式` 必须明确设为 `大模型识别`（从用户输入提取）或 `业务透传`（由外部传入，通过 `biz_params` 或 `user_defined_params`）；
|
||||
- `参数类型` 支持 Number/String/Object 等，Object 类型子属性**不能为空**，需手动添加 [自定义插件](../../raw/application-user-guide/plug-in/custom-plug-ins.md)。
|
||||
- **鉴权配置**：自定义插件可启用 Header 或 Query 鉴权，`Token` 值需按 `Type`（basic/bearer/appcode）格式注入请求头或 URL。
|
||||
- `传参方式`：`大模型识别`（从用户输入提取）或 `业务透传`（由外部传入，需通过 `biz_params` 或 `user_defined_params` 指定）；
|
||||
- `类型`：支持 `String`、`Number`、`Object`（Object 的子属性**不能为空**，须显式添加）；
|
||||
- `必填`：影响大模型参数构造逻辑，非必填参数可能被忽略。
|
||||
- **鉴权配置**：支持 `Header`（如 `Authorization: Bearer <TOKEN>`）或 `Query`（如 `?api_key=xxx`）方式，鉴权类型包括 `basic`、`bearer`、`appcode`。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **权限准备**：主账号或 RAM 子账号首次使用插件前，必须授权服务关联角色 `AliyunServiceRoleForSFMAccessCloudAPI`；RAM 用户需额外授予 `ram:CreateServiceLinkedRole` 权限（策略条件中 `ram:ServiceName` 应为 `cloundapi-access.sfm.aliyuncs.com`）[官方和第三方插件](../../raw/application-user-guide/plug-in/plugins.md)。
|
||||
1. **权限准备**：主账号或 RAM 子账号需先授权服务关联角色 `AliyunServiceRoleForSFMAccessCloudAPI`，子账号还需额外授予 `ram:CreateServiceLinkedRole` 权限（策略条件需匹配 `cloundapi-access.sfm.aliyuncs.com`）[官方和第三方插件](../../raw/application-user-guide/plug-in/plugins.md)。
|
||||
2. **插件接入**：
|
||||
- 官方/三方插件：在插件市场页面单击“添加至智能体”，选择目标智能体应用（同一业务空间），最多支持 10 个工具 [官方和第三方插件](../../raw/application-user-guide/plug-in/plugins.md)；
|
||||
- 自定义插件：需先发布为 MCP 服务，再于智能体编排页的“MCP”区块中添加 [自定义插件](../../raw/application-user-guide/plug-in/custom-plug-ins.md)；
|
||||
- 工作流应用：将插件作为独立节点拖入流程，手动编排执行顺序；
|
||||
- Assistant API：在 `tools` 字段中声明工具列表，由模型自主决策调用时机与参数 [插件概述](../../raw/application-user-guide/plug-in/plug-in-overview.md)。
|
||||
3. **调试与发布**：所有自定义工具必须通过“测试工具”验证连通性，并点击“发布”后才可在应用中生效；草稿状态工具不可调用。
|
||||
- *官方/三方插件*：在插件市场页面单击“添加至智能体”，选择目标智能体（**仅限同业务空间**），最多添加 10 个工具；
|
||||
- *自定义插件*：创建后需发布为 MCP 服务，再在智能体编排页的“MCP”区块中添加；
|
||||
- *工作流应用*：将插件作为独立节点拖入流程，按需配置输入输出；
|
||||
- *Assistant API*：在 `tools` 数组中声明工具定义，调用时由模型自动规划并触发。
|
||||
3. **调试与发布**：所有自定义工具必须完成在线测试（“测试工具”按钮）且状态为“成功”，再点击“发布”方可生效；草稿状态工具不可调用。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **调用限制**：智能体应用中最多添加 10 个工具；自定义插件的 `工具名称` 不得超过 20 字符 [自定义插件](../../raw/application-user-guide/plug-in/custom-plug-ins.md)。
|
||||
- **功能限制**：
|
||||
- `code_interpreter` 不支持网络访问与本地文件上传，依赖库版本固定（如 `requests~=2.31.0`、`pandas` 等）；
|
||||
- `quark_search` 和 `github_search` 均仅返回摘要信息，不支持访问原始网页或 GitHub 仓库详情页；
|
||||
- GET 请求方法下，输入参数**不支持 Object 类型**（错误码 130022）[自定义插件](../../raw/application-user-guide/plug-in/custom-plug-ins.md)。
|
||||
- **安全与维护**：
|
||||
- 删除插件或工具将导致所有关联应用失效，且操作不可逆；
|
||||
- 修改插件 URL 或鉴权配置后，必须重新测试并发布所有下属工具；
|
||||
- 通过 API 调用含业务透传参数或用户级鉴权的插件时，必须通过 `biz_params` 传递对应值。
|
||||
- 官方插件无需配置参数，但**仅限与插件所在业务空间相同的智能体应用关联**；子业务空间调用官方插件需单独授权。
|
||||
- 自定义插件的 `Object` 类型输入参数在 `GET` 请求下**不支持**，仅 `POST` 允许；`Object` 的子属性必须显式定义，否则发布失败（错误码 `130022`）。
|
||||
- `code_interpreter` 插件禁用网络访问、文件系统读写及敏感模块（如 `os.system`），可用依赖版本严格限定，详见 [官方和第三方插件](../../raw/application-user-guide/plug-in/plugins.md)。
|
||||
- 删除插件或工具将导致**已关联的应用立即失效**，且操作不可逆；编辑插件 URL 或鉴权信息后，必须重新测试并发布所有相关工具。
|
||||
- 多插件组合调用（如 `quark_search` + `text_to_image` + `generate_qrcode`）支持，但需确保各工具返回结构能被大模型正确解析与串联。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,57 +1,54 @@
|
||||
# prompt
|
||||
|
||||
Prompt 是百炼平台中用于引导大语言模型生成预期输出的核心指令载体。它既可作为静态文本直接调用模型，也可通过模板化、样例增强、自动优化等机制实现结构化管理与效果提升。合理设计 Prompt 是保障模型输出准确性、一致性与业务适配性的关键环节，适用于文本生成、图片生成、智能体应用构建等多种场景。
|
||||
Prompt 是百炼平台中驱动大语言模型行为的核心指令载体。通过结构化设计、模板化管理、样例引导和自动优化等能力，开发者可高效构建稳定、可控、可复用的提示词逻辑，显著提升模型输出质量与业务适配性。所有 Prompt 相关功能均需在华北2（北京）地域使用。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
百炼平台提供多种 Prompt 相关能力，覆盖从基础指令构造到高级工程化优化的全链路：
|
||||
百炼平台提供多层次 Prompt 支持能力，覆盖从基础指令到复杂工程化场景：
|
||||
|
||||
- **Prompt 模板**：支持预置模板（如营销文案生成、摘要抽取）和自定义模板（含文本生成与图片生成两类），通过变量插值（如 `${topic}`）实现动态内容填充。详见 [Prompt模板概述](../../raw/application-user-guide/prompt/prompt-template.md)。
|
||||
- **Prompt 样例库**（已下线）：曾支持通过少样本问答对（user input / model output）引导模型风格与格式，但该功能[已不再维护](../../raw/application-user-guide/prompt/prompt-sample-optimization.md)，官方明确推荐迁移至 RAG 表格库。
|
||||
- **Prompt 自动优化**：基于大模型对原始 Prompt 进行结构重组、角色注入、指令增强与安全边界补充，无需人工 [Prompt 工程](../concepts/prompt-engineering.md)经验。该功能不计费，且用户数据不会用于模型训练 [Prompt自动优化](../../raw/application-user-guide/prompt/optimize-prompt.md)。
|
||||
- **Prompt 反馈优化**：基于用户提供的输入输出样例（few-shot）及评测数据集，通过多轮自动化评估与反思生成更贴合实际业务效果的 Prompt，尤其适用于分类、结构化输出等任务。
|
||||
|
||||
> **注意**：文档 2 中描述的 Prompt 样例库功能已正式停用，所有新项目应避免依赖该能力；现有应用需按指引迁移至 RAG 表格库。
|
||||
- **Prompt 模板**：支持预置模板（如营销文案生成、摘要抽取）和自定义模板，后者可基于 [ICIO、CRISPE、RASCEF 等 Prompt 工程框架](../../raw/application-user-guide/prompt/prompt-custom-template.md) 结构化构建，适用于文本生成与图片生成两类任务（后者需分别配置正向/负向 Prompt）[原文标题](../../raw/application-user-guide/prompt/prompt-template.md)。
|
||||
- **Prompt 样例库**：通过少样本学习（Few-shot）注入高质量问答对，引导模型输出风格与格式一致性。> **注意**：该功能已停止维护，[官方明确建议迁移至 RAG 表格库](../../raw/application-user-guide/prompt/prompt-sample-optimization.md)，不再新增或更新样例库能力。
|
||||
- **Prompt 自动优化**：基于大模型对原始 Prompt 进行结构重组、角色设定、指令增强与安全边界注入，无需人工 [Prompt 工程](../concepts/prompt-engineering.md)经验即可获得更清晰、稳定的版本[原文标题](../../raw/application-user-guide/prompt/optimize-prompt.md)。
|
||||
- **Prompt 反馈优化**：利用用户提供的输入输出样例（query-answer pairs）进行多轮评估与迭代，生成带 few-shot 示例和边界说明的高精度 Prompt，尤其适用于分类、结构化输出等确定性任务[原文标题](../../raw/application-user-guide/prompt/prompt-feedback-optimization.md)。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 说明 | 取值范围/约束 | 来源 |
|
||||
|------|------|----------------|------|
|
||||
| `promptTemplateId` | 模板唯一标识符，用于 API 获取模板内容 | 字符串，由平台生成 | [Prompt模板概述](../../raw/application-user-guide/prompt/prompt-template.md) |
|
||||
| `workspaceId` | 业务空间 ID，必需参数，用于鉴权与资源隔离 | 字符串，需通过控制台或 API 获取 | [Prompt模板概述](../../raw/application-user-guide/prompt/prompt-template.md) |
|
||||
| `variables` | 模板中声明的变量名列表（如 `["platform", "topic"]`），用于运行时填充 | JSON 数组，最大支持 64 个变量 | [Prompt模板概述](../../raw/application-user-guide/prompt/prompt-template.md) |
|
||||
| `has_thoughts` | API 调用时启用样例检索调试信息（仅限历史兼容场景） | `true` / `false`，仅在样例库功能有效期内适用 | [使用Prompt样例库优化模型输出](../../raw/application-user-guide/prompt/prompt-sample-optimization.md) |
|
||||
| 召回片段数 | 关联样例库时注入上下文的样例数量（已下线） | 默认 5，上限 10 | [使用Prompt样例库优化模型输出](../../raw/application-user-guide/prompt/prompt-sample-optimization.md) |
|
||||
| 参数 | 说明 | 来源/约束 |
|
||||
|------|------|-----------|
|
||||
| `promptTemplateId` | 模板唯一标识符，用于 API 调用获取模板内容 | 通过控制台模板卡片或 `CreatePromptTemplate` 接口返回获取 |
|
||||
| `workspaceId` | 业务空间 ID，所有 Prompt 操作必须指定有效 workspace | 需提前通过 [获取 APP ID 和 Workspace ID](https://help.aliyun.com/zh/model-studio/obtain-the-app-id-and-workspace-id) 获取 |
|
||||
| `variables` | 模板中声明的变量名数组（如 `["platform", "topic"]`），用于运行时填充 | 由 `GetPromptTemplate` 接口响应返回，不可在调用时动态增删 |
|
||||
| `has_thoughts` | API 请求参数，设为 `true` 时可在响应 `thoughts` 字段中查看样例检索详情 | 仅适用于已关联样例库的智能体应用调用（见 [Prompt样例库优化文档](../../raw/application-user-guide/prompt/prompt-sample-optimization.md)） |
|
||||
| 召回片段数 | 单次请求注入上下文的样例数量，默认 5，上限 10 | 在智能体应用配置中调整，影响 [Token](../concepts/token.md) 成本与效果平衡 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 控制台操作
|
||||
- **模板创建与管理**：进入「组件管理 > 提示词」页面，支持自定义创建、基于 [Prompt 工程](../concepts/prompt-engineering.md)框架（ICIO/CRISPE/RASCEF）创建，或复制预置模板进行二次开发。
|
||||
- **自动优化**：在「提示词 > 自动优化」页面粘贴原始 Prompt，点击「优化」获取增强版本，支持一键「保存为模板」。
|
||||
- **反馈优化**：在「提示词 > 反馈优化」页面配置初始 Prompt、上传样例数据（建议 5–10 条，覆盖全部类别）与评测数据（建议 ≥20 条），启动多轮优化任务。
|
||||
- **模板创建**：进入「组件管理 > 提示词」，选择「创建提示词」，按类型（文本/图片生成）与输入模式（自定义 / 基于 [Prompt 工程](../concepts/prompt-engineering.md)）配置并保存。
|
||||
- **样例库关联**：在智能体应用「配置」页启用「样例库」开关，选择已创建的样例库（最多 5 个），发布后生效。
|
||||
- **自动优化**：在「提示词 > 自动优化」页面粘贴原始 Prompt，点击「优化」，结果可直接复制或「保存为模板」。
|
||||
|
||||
### API 调用
|
||||
- **获取模板**：调用 `GetPromptTemplate` 接口，传入 `workspaceId` 和 `promptTemplateId`，响应中包含 `content`（模板字符串）与 `variables`（变量列表）。
|
||||
- **渲染模板**：将业务数据按 `variables` 键名填入模板字符串（如 `content.replace('${topic}', 'AI芯片')`），生成最终 Prompt。
|
||||
- **调用模型**：将渲染后的 Prompt 作为 `messages` 或 `system` 字段传入模型推理 API（如 `ChatCompletion`）。
|
||||
|
||||
### SDK 示例
|
||||
SDK 示例代码（Java/Python 等）可在 `GetPromptTemplate` 接口文档的「SDK 示例」页签中自动生成，自动注入 `workspaceId` 和 `promptTemplateId`，开发者仅需配置 `accessKeyId` 和 `accessKeySecret` 即可运行。
|
||||
### API/SDK 调用
|
||||
- **获取模板**：调用 `GetPromptTemplate` 接口（需 `workspaceId` + `promptTemplateId`），响应含 `content` 与 `variables`，填入变量后即可发送至模型。
|
||||
- **反馈优化任务**：调用 `CreatePromptFeedbackOptimizationTask`（需推理模型、初始 Prompt、样例数据集、评测数据集），任务完成后获取优化版 Prompt。
|
||||
- **应用调用**：若已关联样例库，设置 `has_thoughts=true` 可调试召回过程；模板类应用需先渲染 Prompt 再调用模型 API。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域限制**：所有 Prompt 模板功能（包括创建、获取、使用）当前**仅支持华北2（北京）地域**，跨地域调用将失败。
|
||||
- **字符长度**：控制台编辑器中 Prompt 内容最大支持 **6144 字符**；API 层面受模型最大上下文限制（如 Qwen-Max 为 32K tokens），需自行校验总 token 数。
|
||||
- **模板变量**：变量语法为 `${variableName}`，不支持嵌套或表达式（如 `${a.b}` 或 `${x + y}`）。
|
||||
- **图片生成模板**：仅支持文本生成与图片生成两类，图片模板需分别配置正向 Prompt（期望内容）与负向 Prompt（排除内容）。
|
||||
- **数据安全**：Prompt 自动优化与反馈优化过程中，用户提交的原始 Prompt 和样例数据**不会被存储或用于模型训练**，符合阿里云数据隐私政策。
|
||||
- **成本影响**：启用样例库（已下线）或反馈优化会显著增加输入 token 消耗；反馈优化本身不计费，但其产出的 Prompt 若导致更长输入或更高频调用，将间接影响模型调用费用。
|
||||
- **地域限制**：所有 Prompt 功能（模板、样例库、优化）**仅支持华北2（北京）地域**，跨地域调用将失败。
|
||||
- **容量限制**：
|
||||
- 单个 Prompt 模板内容最大 6144 字符（控制台编辑框右下角实时计数）；
|
||||
- 单个样例库最多 300 条样例，单次批量导入 Excel ≤ 20MB 且 ≤ 100 条；
|
||||
- 单个智能体应用最多关联 5 个样例库，单次召回最多 10 个样例片段。
|
||||
- **数据安全**：Prompt 自动优化与反馈优化过程中提交的数据**不会被存储或用于模型训练**，符合阿里云数据隐私政策[原文标题](../../raw/application-user-guide/prompt/optimize-prompt.md)。
|
||||
- **过时功能警示**：Prompt 样例库功能已下线，新项目请勿依赖；存量应用应尽快按 [迁移指南](../../raw/application-user-guide/prompt/prompt-sample-optimization.md) 迁移至 RAG 表格库。
|
||||
- **模型兼容性**：反馈优化推荐使用 `qwen-max` 作为推理模型；图片生成模板仅适配通义万相等图像模型，不适用于文本模型。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [Prompt模板概述](../../raw/application-user-guide/prompt/prompt-template.md)
|
||||
- [使用Prompt样例库优化模型输出](../../raw/application-user-guide/prompt/prompt-sample-optimization.md)
|
||||
- [自定义Prompt模板](../../raw/application-user-guide/prompt/prompt-custom-template.md)
|
||||
- [使用Prompt样例库优化模型输出](../../raw/application-user-guide/prompt/prompt-sample-optimization.md)
|
||||
- [Prompt自动优化](../../raw/application-user-guide/prompt/optimize-prompt.md)
|
||||
- [基于大模型输入输出样例的Prompt自动优化](../../raw/application-user-guide/prompt/prompt-feedback-optimization.md)
|
||||
|
||||
|
||||
@@ -1,58 +1,36 @@
|
||||
# release notes
|
||||
|
||||
本页汇总百炼平台近期模型与功能更新，涵盖新模型上线、已有模型能力演进、平台功能迭代及关键使用约束。所有信息均基于官方发布内容整理，面向开发者提供可直接用于集成与调用的结构化参考。模型能力以实际 API 接口为准，建议结合 [原文标题](../../raw/model-user-guide/release-notes/newly-released-models.md) 和 [原文标题](../../raw/model-user-guide/release-notes/model-release-notes.md) 查阅原始技术细节与上下文。
|
||||
本页汇总百炼平台近期模型与功能更新，涵盖新模型上线、已有模型能力增强、平台功能迭代及关键使用变更。所有信息均基于官方发布内容整理，面向开发者提供可直接落地的参考依据。建议结合具体业务场景选择适配模型，并关注下线通知以规避服务中断风险。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **文本生成与深度思考**：新增 `qwen3.7-flash`（2026-07-21）、`glm-5.2-fast-preview`（2026-07-09）、`xiaomi/mimo-v2.5-pro`（2026-05-18）等模型；`kimi/kimi-k3`（2026-07-17）为首个开源 2.8T 参数模型，支持 100 万 token 上下文与原生视觉理解。
|
||||
- **多模态与视觉理解**：`qwen3.7-flash`、`qwen3.7-plus`、`qwen3.7-max-2026-06-08` 均强化视觉-语言联合推理与 Agent 执行能力；`qwen3.5-ocr`（2026-06-16）专精文档解析与卡证关键信息抽取。
|
||||
- **图像生成**：`qwen-image-3.0-pro`（2026-07-20）支持 4.5k token 输入、10px 小字渲染与 12 国语言字体原生渲染；`vidu/viduq3-fast_reference2image`（2026-07-09）成本较 Pro 版降低约 50%。
|
||||
- **视频生成**：`vidu/viduq3-drama_reference2video`（2026-07-09）专注剧集一致性与动效美学；`pixverse/pixverse-motioncontrol`（2026-07-14）支持从参考视频提取动作并迁移至目标人物图；`wan2.7-r2v-2026-06-12`（2026-07-01）支持最多 5 图/视频混合参考及音频音色参考。
|
||||
- **语音与音频**：`qwen-audio-3.0-tts-plus`（2026-07-14）强调音质与表现力，适用于有声书/影视配音；`qwen-audio-3.0-tts-flash` 首包延时 ≤200ms，适配语音助手等低延迟场景；`fun-asr-flash-2026-06-15` 支持 30 语种及汉语七大方言体系。
|
||||
- **向量与嵌入**：`qwen3.7-text-embedding`（2026-07-15）支持 256~2560 维自定义输出维度，在 MTEB 多语言检索任务上效果提升 20%。
|
||||
- **平台级功能**：新增知识检索服务与知识问答服务（2026-06-23）、智能体托管运行时 API（2026-06-29）、Skill 能力包（2026-06-10）、数据连接模块（2026-06-10）、Responses API 异步调用（2026-06-01）；模型调优已支持图像生成、视觉理解、视频生成三类模型（见 [原文标题](../../raw/model-user-guide/release-notes/model-release-notes.md)）。
|
||||
- **文本生成与智能体**：新增 `qwen3.7-flash`（2026-07-21）、`glm-5.2-fast-preview`（2026-07-09）、`kimi/kimi-k3`（2026-07-17）等高吞吐/长上下文模型；`qwen3.7-max-2026-06-08` 已支持视觉模态理解，具备[多模态](../concepts/multi-modal.md)交互混合智能体能力。
|
||||
- **[多模态](../concepts/multi-modal.md)生成**：图片生成新增 `qwen-image-3.0-pro`（2026-07-20），支持 4.5k token 输入与 10px 小字精准渲染；视频生成新增 `vidu/viduq3-pro-fast_img2video`（2026-07-09）、`pixverse/pixverse-motioncontrol`（2026-07-14）等专用能力模型。
|
||||
- **语音与音频**：实时语音合成新增 `qwen-audio-3.0-tts-plus`（高质量）与 `qwen-audio-3.0-tts-flash`（低延迟）双版本；实时语音对话新增 `qwen-audio-3.0-realtime-plus` 与 `qwen-audio-3.0-realtime-flash`，端到端响应时延优化至低水平。
|
||||
- **向量与识别**：文本向量新增 `qwen3.7-text-embedding`（2026-07-15），支持 256~2560 维自定义维度；OCR 新增 `qwen3.5-ocr`（2026-06-16），在卡证类业务场景抽取效果显著提升。
|
||||
- **平台级能力**：新增 [模型平台功能更新](../../raw/model-user-guide/release-notes/model-release-notes.md) 中描述的多项能力，包括知识检索服务、智能体托管运行时 API、Skill 能力包、数据连接模块等，详见该文档。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **上下文长度**：`kimi/kimi-k3`、`glm-5.2`、`deepseek-v4-pro`、`xiaomi/mimo-v2.5-pro` 等主流旗舰模型均支持 100 万 token 上下文；`qwen-audio-3.0-realtime-plus` 未公开上下文长度，但明确标注“端到端响应时延控制在低水平”。
|
||||
- **输入限制**：
|
||||
- 图片生成类（如 `vidu/viduq2-pro_reference2image`）支持 0–14 张参考图；
|
||||
- 视频生成类（如 `pixverse/pixverse-v6-r2v`）支持 2–7 张图像输入；
|
||||
- `fun-asr-flash-2026-06-15` 支持 ≤5 分钟音频转写。
|
||||
- **输出控制**：
|
||||
- `qwen-audio-3.0-tts-plus` 与 `qwen-audio-3.0-tts-flash` 均支持细粒度标签控制情绪、语气、角色、语速、音量；
|
||||
- `pixverse/pixverse-lipsync` 支持嘴部动作与输入音频/TTS 精准同步；
|
||||
- `qwen3.7-text-embedding` 允许用户指定向量维度（256–2560）。
|
||||
- **性能指标**：
|
||||
- `kimi/kimi-k2.7-code-highspeed` 输出速度约 180 [Token](../concepts/token.md)/s（中位数输入），短上下文可达 260 [Token](../concepts/token.md)/s；
|
||||
- `qwen-audio-3.0-tts-flash` 首包延时 ≤200ms；
|
||||
- `Tripo/Tripo-P1.0` 生成专业级拓扑 3D 资产耗时约 2 秒。
|
||||
|
||||
> **注意**：文档 1 中 `kimi/kimi-k2.7-code`（2026-06-15）与 `kimi/kimi-k2.7-code-highspeed`（2026-06-17）被描述为“同一个模型”，但文档 1 同时列出二者为独立模型 ID，且后者明确标注“输出速度约为普通版的 5–6 倍”。实际调用时请以 API 文档中 `model_id` 实际可用性为准，避免混淆。
|
||||
- **上下文长度**：`kimi/kimi-k3`、`glm-5.2`、`deepseek-v4-pro` 等主流旗舰模型均支持 100 万 token 上下文；`qwen3.7-flash` 等 Flash 系列模型在保持长上下文的同时侧重推理速度优化。
|
||||
- **输入限制**：`vidu/viduq3-fast_reference2image` 支持 0–14 张参考图；`pixverse/pixverse-v6-r2v` 支持 2–7 张图像输入；`fun-asr-flash-2026-06-15` ASR 模型支持 ≤5 分钟音频转写。
|
||||
- **性能指标**：`qwen-audio-3.0-tts-flash` 首包延时 ≤200ms；`kimi/kimi-k2.7-code-highspeed` 编程输出速度达 180–260 [Token](../concepts/token.md)/s；`qwen3.7-text-embedding` 在 MTEB 多语言检索任务上效果提升 20%。
|
||||
- **部署规格**：模型部署支持按模型单元（MU）时长计费，详见 [模型平台功能更新](../../raw/model-user-guide/release-notes/model-release-notes.md) 中“1月23日”条目。
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **模型调用**：所有模型通过百炼统一 API 接口调用，支持 OpenAI-compatible（`/v1/chat/completions`）与 DashScope 原生协议（`/v1/services/aigc/text-generation/generation`）。具体 endpoint、鉴权方式与请求格式详见各模型文档。
|
||||
- **平台功能接入**：
|
||||
- 新增功能如 Skill 能力包、数据连接模块、知识检索服务均需通过对应 API 或控制台启用；
|
||||
- Responses API 异步调用需设置 `background=true` 并轮询 `/v1/async_tasks/{task_id}` 获取结果；
|
||||
- 智能体托管运行时（Managed Agent）需调用 `/v1/agents/run` 接口，会话与工具执行由平台托管。
|
||||
- **模型部署与调优**：
|
||||
- 预置模型（如 `qwen-flash`、`qwen-plus`）支持通过 API 直接部署（见 [原文标题](../../raw/model-user-guide/release-notes/model-release-notes.md)）；
|
||||
- 自定义模型导入支持 LoRA 微调模型从 OSS 导入（2026-06-05 国际站上线）；
|
||||
- 视觉理解、视频生成、图像生成模型均已开放 SFT/DPO/RL 训练支持（见 [原文标题](../../raw/model-user-guide/release-notes/model-release-notes.md)）。
|
||||
- **API 调用**：文本生成统一入口已聚合 OpenAI Responses 与 Anthropic Messages 接口分类（[详见文档2 5月15日更新](../../raw/model-user-guide/release-notes/model-release-notes.md)）；Responses API 新增 `background=true` 异步调用模式（2026-06-01）。
|
||||
- **SDK 接入**：[多模态](../concepts/multi-modal.md)交互开发套件已提供 Linux C++、Android、iOS Lite、RTOS C 等多端 SDK（[详见文档2 2月/4月条目](../../raw/model-user-guide/release-notes/model-release-notes.md)）；Spring AI Alibaba 框架调用百炼应用文档已上线（2026-06-01）。
|
||||
- **模型部署**：预置吞吐部署（PTU）新增长输入与前缀缓存能力（2026-06-15）；国际站支持从 OSS 导入 LoRA 微调模型（2026-06-05）。
|
||||
- **智能体开发**：可通过 Skill 能力包添加官方或自定义技能（2026-06-10）；Managed Agent 运行时 API 支持平台托管会话与工具执行（2026-06-29）。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **模型下线**：平台按季度清理老旧模型，2026年7月已发布《部分老旧模型下线通知》与《部分老旧长尾模型下线通知》；历史快照模型（如 `wan2.7-t2v-2026-04-25`）可能随时不可用，生产环境应避免硬编码快照 ID。
|
||||
- **地域与权限**：新增美国、德国、日本地域部署（2026-06-12），但部分模型（如 `qwen-audio-3.0-realtime-plus`）当前仅限华北2（北京）可用；API Key 加密存储与业务空间专属域名已于 2026-06-29 升级，旧域名将逐步停用。
|
||||
- **资源与计费**：
|
||||
- `qwen-turbo` 资源包已启动退市（2026-06-28）；
|
||||
- 记忆库、Managed Agent、企业知识库（旧）等平台功能已商业化或下线（2026-07）；
|
||||
- 模型上下文缓存、Qwen-VL 系列、千问系列模型均有降价通知（见 [原文标题](../../raw/model-user-guide/release-notes/model-release-notes.md)）。
|
||||
- **兼容性风险**：
|
||||
- `qwen3.7-max`（2026-05-21）与 `qwen3.7-max-2026-05-20` 在文档 1 中并存，但后者为前者的快照标识；实际调用应优先使用无时间后缀的 `qwen3.7-max`，其能力随平台自动更新；
|
||||
- `vidu/viduq3-mix_reference2video`（2026-04-28）与 `vidu/viduq3_reference2video`（2026-04-27）功能描述高度重合，且均标注“万物可参，声画同出”，建议以最新版本 `viduq3-mix` 为准，旧版可能受限或归档。
|
||||
- > **注意**：文档1中 `kimi/kimi-k2.7-code`（2026-06-15）与 `kimi/kimi-k2.7-code-highspeed`（2026-06-17）被描述为“同一个模型”，但文档1未说明二者是否共享同一模型 ID 或 API 路径。实际调用前请以 [模型上下架与更新](../../raw/model-user-guide/release-notes/newly-released-models.md) 中列出的模型 ID 为准，并验证接口兼容性。
|
||||
- > **注意**：文档2中“7月10日”与“7月9日”分别提及“部分老旧模型下线”和“部分老旧长尾模型下线”，但未明确具体模型清单；而文档1中大量模型（如 `qwen3.6-flash-2026-04-16`、`qwen-image-2.0-pro-2026-04-22`）标注为历史快照版。建议开发者主动查阅 [模型下线机制说明](https://help.aliyun.com/zh/model-studio/model-depreciation) 并监控控制台通知，避免依赖已标记为“快照”或无后续更新的模型。
|
||||
- 所有 Flash/Plus/Pro/Turbo 等后缀模型均代表不同性能-成本权衡点，例如 `qwen-audio-3.0-tts-flash` 侧重低延迟，`qwen-audio-3.0-tts-plus` 侧重音质细节，不可混用配置参数。
|
||||
- 视频生成类模型（如 `vidu/viduq3-drama_reference2video`、`wan2.7-r2v-2026-06-12`）对输入参考图数量、格式、分辨率有明确要求，超出范围将导致任务失败或效果劣化，需严格遵循各模型文档说明。
|
||||
- 模型调优功能当前对部分模型类型（如视频生成、VL 模型）仍为邀约制或有限开放（见 [模型平台功能更新](../../raw/model-user-guide/release-notes/model-release-notes.md) 中 5月31日、5月28日、1月21日条目），非全量可用。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,74 +1,75 @@
|
||||
# security and compliance
|
||||
|
||||
阿里云百炼平台提供多层次的安全与合规能力，覆盖模型调用、数据传输、存储隔离、内容审核及监管备案等关键环节。开发者可通过权限管理、AI安全护栏、私网接入、端到端加密等机制，满足企业级数据安全、等保要求及《生成式人工智能服务管理暂行办法》等法规义务。所有功能均基于阿里云统一安全底座，支持SOC 2审计认证，并默认禁用客户数据用于模型训练。
|
||||
阿里云百炼平台提供多层次的安全与合规能力，覆盖模型调用、数据传输、网络隔离、算法备案及隐私保护等关键环节。开发者可通过权限管理、AI安全护栏、加密传输、私网接入和合规材料获取等功能，满足生产环境下的安全要求与监管合规义务。所有功能均需结合业务空间（Workspace）粒度进行配置，且部分能力（如私网访问、安全存储）依赖特定地域与资源组合。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **AI安全护栏**：支持文本与图片类模型（如`qwen-plus`、`wanxiang`）的输入输出内容审核，需显式启用 `X-DashScope-DataInspection` 请求头 [输⼊输出AI安全护栏](../../raw/model-user-guide/security-and-compliance/content-security.md)。
|
||||
- **加密推理**：支持对请求体中 `input` 字段进行AES-RSA混合加密，仅适用于DashScope原生Endpoint（不支持OpenAI兼容模式），需配合公钥接口获取最新密钥 [获取RSA的公钥](../../raw/model-user-guide/security-and-compliance/transmission-security/model-interface-aes-encryption.md)。
|
||||
- **私网访问**：支持通过PrivateLink终端节点实现VPC内私网调用百炼API，当前覆盖华北2（北京）和新加坡地域，美国（弗吉尼亚）暂不支持 [通过终端节点私网访问阿里云百炼模型或应用 API](../../raw/model-user-guide/security-and-compliance/transmission-security/access-model-studio-through-privatelink.md)。
|
||||
- **安全存储空间**：面向高敏感场景提供独立业务空间类型，支持配置OSS、ADB、ElasticSearch等私有网络资源，并强制要求终端节点+可用区IP+MSE网关三级网络隔离 [配置终端节点并发起连接](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-an-endpoint-and-initiate-a-connection.md)。
|
||||
- **AI安全护栏服务**：支持文本与图片类模型的输入输出内容审核，需显式启用 `X-DashScope-DataInspection` 请求头 [输⼊输出AI安全护栏](../../raw/model-user-guide/security-and-compliance/content-security.md)。
|
||||
- **加密传输能力**：支持对请求体 `input` 字段进行 AES-RSA 混合加密，防止公网传输中敏感数据泄露；仅适用于 DashScope Endpoint，[OpenAI 兼容接口](../concepts/openai-compatible-interface.md)不支持 [以加密的方式接入模型推理功能](../../raw/model-user-guide/security-and-compliance/transmission-security/encrypted-access-to-model-inference.md)。
|
||||
- **私网访问能力**：通过阿里云 PrivateLink 创建接口终端节点（Endpoint），实现 VPC 内资源直连百炼 API，流量全程不经过公网 [通过终端节点私网访问阿里云百炼模型或应用 API](../../raw/model-user-guide/security-and-compliance/transmission-security/access-model-studio-through-privatelink.md)。
|
||||
- **安全存储业务空间**：支持在私有网络中集成 OSS、ADB、ElasticSearch 等云组件，构建端到端隔离的数据存储与处理环境，需配合终端节点、可用区 IP 和 MSE 网关完成部署 [配置终端节点并发起连接](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-an-endpoint-and-initiate-a-connection.md)。
|
||||
|
||||
> **注意**：文档 7 与文档 8 均描述私网接入，但适用场景不同：文档 7 针对「安全存储业务空间」（反向终端节点 + 安全存储组件），文档 8 针对「通用模型/API 调用」（接口终端节点 + 直接访问 DashScope）。二者不可混用，且文档 7 明确限定于华北2（北京）地域，而文档 8 同时支持华北2（北京）和新加坡地域。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数名 | 说明 | 示例值 | 来源 |
|
||||
|--------|------|--------|------|
|
||||
| `X-DashScope-DataInspection` | 启用AI安全护栏，控制输入/输出检查开关 | `{"input":"cip","output":"cip"}` | [输⼊输出AI安全护栏](../../raw/model-user-guide/security-and-compliance/content-security.md) |
|
||||
| `X-DashScope-EncryptionKey` | 加密调用必需头，含`public_key_id`、`encrypt_key`、`iv` | `{"public_key_id":"1","encrypt_key":"...","iv":"..."}` | [以加密的方式接入模型推理功能](../../raw/model-user-guide/security-and-compliance/transmission-security/encrypted-access-to-model-inference.md) |
|
||||
| `enable_encryption=True` (Python) / `.enableEncrypt(true)` (Java) | DashScope SDK加密开关，自动处理加解密逻辑 | `True` | [以加密的方式接入模型推理功能](../../raw/model-user-guide/security-and-compliance/transmission-security/encrypted-access-to-model-inference.md) |
|
||||
| `dashscope.base_http_api_url` | SDK自定义API基础地址，用于私网终端节点调用 | `"http://ep-xxx.dashscope.cn-beijing.privatelink.aliyuncs.com/api/v1"` | [通过终端节点私网访问阿里云百炼模型或应用 API](../../raw/model-user-guide/security-and-compliance/transmission-security/access-model-studio-through-privatelink.md) |
|
||||
|
||||
> **注意**：文档12中明确指出OpenAI兼容模式（`/compatible-mode/v1`）**不支持**加密调用，但文档10未强调此限制，实际使用时必须避免在OpenAI兼容Endpoint上设置`X-DashScope-EncryptionKey`或启用SDK加密参数，否则将返回400错误。
|
||||
| 参数 | 说明 | 来源 |
|
||||
|------|------|------|
|
||||
| `X-DashScope-DataInspection` | 启用 AI 安全护栏的请求头，值为 `{"input":"cip","output":"cip"}`，表示对输入和输出均执行内容检查 | [输⼊输出AI安全护栏](../../raw/model-user-guide/security-and-compliance/content-security.md) |
|
||||
| `X-DashScope-EncryptionKey` | 加密调用必需请求头，包含 `public_key_id`、`encrypt_key`（RSA 加密后的 AES 密钥）和 `iv`（初始向量） | [以加密的方式接入模型推理功能](../../raw/model-user-guide/security-and-compliance/transmission-security/encrypted-access-to-model-inference.md) |
|
||||
| `enable_encryption=True`（Python） / `enableEncrypt(true)`（Java） | DashScope SDK 中启用自动加解密的开关参数，SDK 内部封装密钥管理与加解密逻辑 | [以加密的方式接入模型推理功能](../../raw/model-user-guide/security-and-compliance/transmission-security/encrypted-access-to-model-inference.md) |
|
||||
| 终端节点服务域名 | 如 `vpc-cn-beijing.dashscope.aliyuncs.com`（自定义）或 `ep-xxx.privatelink.aliyuncs.com`（默认），用于替换 API `base_url` 实现私网调用 | [通过终端节点私网访问阿里云百炼模型或应用 API](../../raw/model-user-guide/security-and-compliance/transmission-security/access-model-studio-through-privatelink.md) |
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 1. 启用AI安全护栏
|
||||
- 开通AI安全护栏服务并完成RAM授权；
|
||||
- 在请求Header中添加 `X-DashScope-DataInspection: {"input":"cip","output":"cip"}`；
|
||||
- 检查响应状态码：400且`code="data_inspection_failed"`表示内容被拦截。
|
||||
### 1. 启用 AI 安全护栏
|
||||
- 在控制台 [安全管理](https://bailian.console.aliyun.com/?globalset=1#/efm/global_set) 页面完成服务授权；
|
||||
- 调用时在请求头中添加 `X-DashScope-DataInspection: {"input":"cip","output":"cip"}`；
|
||||
- 违规请求将返回 `400` 错误及 `data_inspection_failed` code，响应体含具体拦截原因。
|
||||
|
||||
### 2. 启用端到端加密推理
|
||||
- 调用 `/api/v1/public-keys/latest` 接口获取最新`public_key_id`和公钥；
|
||||
- 生成AES密钥（推荐256位）和IV，用公钥加密AES密钥；
|
||||
- 对`input`字段JSON序列化后AES加密，Base64编码；
|
||||
- 设置`X-DashScope-EncryptionKey`头并发送请求；
|
||||
- **或直接使用DashScope SDK**（Java/Python）：设置`enable_encryption=True`，SDK自动完成全流程。
|
||||
### 2. 启用请求体加密
|
||||
- **SDK 方式（推荐）**：使用 DashScope Python/Java SDK，设置 `enable_encryption=True` 或 `.enableEncrypt(true)`，无需手动管理密钥；
|
||||
- **HTTP 手动方式**：
|
||||
- 调用 `/api/v1/public-keys/latest` 获取最新 RSA 公钥及 `public_key_id` [获取RSA的公钥](../../raw/model-user-guide/security-and-compliance/transmission-security/model-interface-aes-encryption.md)；
|
||||
- 生成 AES 密钥与 IV，用 RSA 公钥加密 AES 密钥；
|
||||
- 将加密后 `input` Base64 编码值、`X-DashScope-EncryptionKey` 头（含 `public_key_id`、`encrypt_key`、`iv`）一并发送；
|
||||
- 响应体中 `output` 字段为 AES 加密结果，需用原始 AES 密钥解密。
|
||||
|
||||
### 3. 私网调用百炼API
|
||||
- 在VPC中创建接口终端节点，服务选择`com.aliyuncs.dashscope`；
|
||||
- 获取终端节点服务域名（如`vpc-cn-beijing.dashscope.aliyuncs.com`）；
|
||||
- 将SDK或HTTP请求的`base_url`替换为该域名；
|
||||
- 确保VPC安全组放行80/443端口入方向流量。
|
||||
### 3. 私网访问百炼 API
|
||||
- 在 VPC 所在地域创建「接口终端节点」，服务选择 `com.aliyuncs.dashscope`；
|
||||
- 开启「自定义服务域名」获取 HTTPS 可用域名（如 `vpc-cn-beijing.dashscope.aliyuncs.com`）；
|
||||
- 将 SDK 或 HTTP 请求的 `base_url` 替换为该域名，保持其他参数（如 `model`、`messages`、`DASHSCOPE_API_KEY`）不变。
|
||||
|
||||
### 4. 配置安全存储空间（高密场景）
|
||||
- 创建类型为“安全存储空间”的业务空间；
|
||||
- 依次完成：终端节点配置 → 可用区IP配置 → OSS/ADB/ES资源配置 → MSE网关路由配置；
|
||||
- 所有资源必须位于同一地域（仅支持华北2（北京））、同一专有网络，且交换机跨至少两个可用区。
|
||||
### 4. 配置安全存储业务空间（高隔离场景）
|
||||
- 创建类型为「安全存储空间」的业务空间；
|
||||
- 按顺序完成：
|
||||
（1）[配置终端节点并发起连接](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-an-endpoint-and-initiate-a-connection.md) →
|
||||
（2）[配置可用区IP](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-zone-ip.md) →
|
||||
（3）[配置私有网络中的资源](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-resources-in-private-network.md)（OSS/ADB/ES）→
|
||||
（4）[配置MSE云原生网关](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-mse.md) →
|
||||
（5）最终激活业务空间。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **权限粒度**：默认业务空间无法设置模型调用/训练/部署限流；仅超级管理员可跨空间管理，业务空间管理员无权操作OpenAPI权限 [权限管理](../../raw/model-user-guide/security-and-compliance/permission-management-overview.md)。
|
||||
- **API Key归属**：自2026年3月25日起，华北2（北京）地域所有新创建API Key均归属主账号，不可分配给RAM用户 [权限管理](../../raw/model-user-guide/security-and-compliance/permission-management-overview.md)。
|
||||
- **地域限制**：
|
||||
- 安全存储空间仅支持华北2（北京）；
|
||||
- 私网终端节点不支持美国（弗吉尼亚）地域；
|
||||
- 模型备案信息需以[互联网信息服务算法备案系统](https://beian.cac.gov.cn)实时查询结果为准，文档中备案号可能滞后 [千问大模型应用上架及合规备案](../../raw/model-user-guide/security-and-compliance/compliance-and-launch-filing-guide-for-ai-apps-powered-by-the-tongyi-model.md)。
|
||||
- **加密兼容性**：加密功能**仅适用于DashScope原生Endpoint**（`/api/v1/...`），OpenAI兼容Endpoint（`/compatible-mode/v1/...`）不支持，强行使用将导致请求失败。
|
||||
- **存储依赖风险**：OSS Bucket或ES实例若被释放，将导致安全存储空间**不可恢复**，必须重建整个业务空间 [配置私有网络中的资源](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-resources-in-private-network.md)。
|
||||
- **API Key 归属约束**：单个 API Key 仅归属一个地域内的一个业务空间和一个用户，不可迁移；自 2026年3月25日起，华北2（北京）地域新创建的 API Key 默认归属主账号 [权限管理](../../raw/model-user-guide/security-and-compliance/permission-management-overview.md)。
|
||||
- **OpenAPI 权限隔离**：RAM 用户默认无权调用知识库、[Prompt 工程](../concepts/prompt-engineering.md)等 OpenAPI，需主账号在 RAM 控制台授予 `AliyunBailianDataFullAccess` 或 `AliyunBailianDataReadOnlyAccess` 策略 [权限管理](../../raw/model-user-guide/security-and-compliance/permission-management-overview.md)。
|
||||
- **模型备案责任主体**：阿里云提供模型算法备案号公示，但应用上架合规（如《生成式人工智能服务管理暂行办法》要求）的主体责任由开发者承担，阿里云不替代履行内容审核、安全评估等法定义务 [千问大模型应用上架及合规备案](../../raw/model-user-guide/security-and-compliance/compliance-and-launch-filing-guide-for-ai-apps-powered-by-the-tongyi-model.md)。
|
||||
- **加密调用兼容性**：仅 DashScope Endpoint（如 `https://dashscope.aliyuncs.com/api/v1`）支持加密，OpenAI 兼容 Endpoint（`/compatible-mode/v1`）不支持 [以加密的方式接入模型推理功能](../../raw/model-user-guide/security-and-compliance/transmission-security/encrypted-access-to-model-inference.md)。
|
||||
- **私网地域限制**：美国（弗吉尼亚）地域暂不支持私网访问；安全存储业务空间仅支持华北2（北京）地域，且专有网络需满足可用区 G/H/L 组合要求 [配置终端节点并发起连接](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-an-endpoint-and-initiate-a-connection.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [权限管理](../../raw/model-user-guide/security-and-compliance/permission-management-overview.md)
|
||||
- [模型备案信息公示](../../raw/model-user-guide/security-and-compliance/model-filing-information-publicity.md)
|
||||
- [输⼊输出AI安全护栏](../../raw/model-user-guide/security-and-compliance/content-security.md)
|
||||
- [模型备案信息公示](../../raw/model-user-guide/security-and-compliance/model-filing-information-publicity.md)
|
||||
- [合规资质与隐私说明](../../raw/model-user-guide/security-and-compliance/privacy-notice.md)
|
||||
- [千问大模型应用上架及合规备案](../../raw/model-user-guide/security-and-compliance/compliance-and-launch-filing-guide-for-ai-apps-powered-by-the-tongyi-model.md)
|
||||
- [配置终端节点并发起连接](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-an-endpoint-and-initiate-a-connection.md)
|
||||
- [配置可用区IP](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-zone-ip.md)
|
||||
- [配置私有网络中的资源](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-resources-in-private-network.md)
|
||||
- [配置MSE云原生网关](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-mse.md)
|
||||
- [以加密的方式接入模型推理功能](../../raw/model-user-guide/security-and-compliance/transmission-security/encrypted-access-to-model-inference.md)
|
||||
- [获取RSA的公钥](../../raw/model-user-guide/security-and-compliance/transmission-security/model-interface-aes-encryption.md)
|
||||
- [配置终端节点并发起连接](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-an-endpoint-and-initiate-a-connection.md)
|
||||
- [通过终端节点私网访问阿里云百炼模型或应用 API](../../raw/model-user-guide/security-and-compliance/transmission-security/access-model-studio-through-privatelink.md)
|
||||
- [获取RSA的公钥](../../raw/model-user-guide/security-and-compliance/transmission-security/model-interface-aes-encryption.md)
|
||||
- [配置私有网络中的资源](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-resources-in-private-network.md)
|
||||
- [配置可用区IP](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-zone-ip.md)
|
||||
- [配置MSE云原生网关](../../raw/model-user-guide/security-and-compliance/secure-storage/configure-mse.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,40 +1,46 @@
|
||||
# skill
|
||||
|
||||
Skill 是百炼平台中用于扩展智能体任务处理能力的可插拔能力包，支持无需编码即可让智能体自动识别并执行文件处理、数据分析等专业任务。它分为官方预置 Skill 和用户自定义 ZIP 技能包两类，通过语义描述驱动调用，适用于对话场景中的自动化任务分发。详细背景见 [Skill (raw/application-user-guide/skill/introduction-to-skill.md)](../../raw/application-user-guide/skill/introduction-to-skill.md)。
|
||||
Skill 是百炼平台中用于扩展智能体任务处理能力的可复用能力包，支持在不编写代码的前提下，让智能体自动识别并执行[文件处理](../concepts/file-processing.md)、数据分析等专业任务。Skill 分为平台预置的官方 Skill 和用户自主开发的自定义 Skill 两类，均通过语义描述驱动调用决策。其核心机制依赖于 `SKILL.md` 中的 `description` 字段对触发条件与能力边界的精准刻画，详见 [Skill (raw/application-user-guide/skill/introduction-to-skill.md)](../../raw/application-user-guide/skill/introduction-to-skill.md)。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **官方 Skill**：平台统一维护的通用能力，覆盖 `.xlsx`、`.csv`、`.pdf`、`.docx` 等常见格式的读取、编辑、转换与清洗，开箱即用，无需配置。最新列表请参考控制台 [Skill 管理](https://bailian.console.aliyun.com/?tab=app#/skill) 页面。
|
||||
- **自定义 Skill**：用户通过上传符合规范的 ZIP 包实现定制化能力，例如行业专用数据解析、私有协议文件处理等。ZIP 包必须包含根目录下的 `SKILL.md` 文件，且整体大小 ≤ 10 MB。具体要求详见 [Skill (raw/application-user-guide/skill/introduction-to-skill.md)](../../raw/application-user-guide/skill/introduction-to-skill.md)。
|
||||
- **适用模型**：Skill 当前仅支持接入基于百炼大模型（如 Qwen 系列）构建的智能体应用，不适用于纯规则引擎或非百炼托管的推理服务。
|
||||
- **核心功能**：
|
||||
- 自动识别用户意图与输入文件/数据特征，匹配最相关的 Skill；
|
||||
- 执行文件解析（如 PDF、Excel、CSV）、结构化数据清洗、格式转换、表格生成等操作；
|
||||
- 输出结果以文件形式返回（如 `.xlsx`、`.pdf`），不支持直接返回数据库写入、API 调用或外部系统状态变更；
|
||||
- 官方 Skill（如 `xlsx`、`pdf`）由平台统一维护，已内置优化的[文件处理](../concepts/file-processing.md)逻辑；自定义 Skill 的行为完全由 ZIP 包内代码与 `SKILL.md` 描述共同决定。
|
||||
|
||||
> **注意**：官方 Skill 不支持用户修改其 `description` 或行为逻辑；所有更新由平台后台统一推送，已添加的应用将自动生效。而自定义 Skill 的版本更新需重新上传 ZIP 包，旧版本不会被自动删除，但已绑定该 Skill 的智能体会立即切换至最新通过审查的版本。
|
||||
> **注意**：原始文档中提及“智能体根据 description 判断是否调用该 Skill”，但实际调用还依赖模型对输入上下文、附件 MIME 类型及历史对话状态的联合判断。单纯优化 `description` 不足以解决所有误触发问题，需结合测试反馈迭代——该细节在 [Skill (raw/application-user-guide/skill/introduction-to-skill.md)](../../raw/application-user-guide/skill/introduction-to-skill.md) 中未明确说明。
|
||||
|
||||
## 关键参数
|
||||
|
||||
自定义 Skill 的核心元信息全部定义在 `SKILL.md`（YAML 格式）中，必需字段如下：
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `name` | 是 | Skill 唯一标识符，仅限小写字母、数字和连字符（如 `invoice-parser`），不可与当前账号下已有 Skill 名重复。 |
|
||||
| `description` | 是 | 决定智能体是否调用该 Skill 的关键依据。需明确说明：① 支持的输入类型（如 `.xlsx`, JSON 表格）；② 可执行操作（如“清洗缺失值”“生成透视表”）；③ 典型触发关键词（如“整理表格”“导出为 CSV”）；④ 明确排除的不适用场景（如“不处理图片内嵌表格”）。描述质量直接影响调用准确率，详见 [Skill (raw/application-user-guide/skill/introduction-to-skill.md)](../../raw/application-user-guide/skill/introduction-to-skill.md) 中的完整示例。 |
|
||||
| 参数 | 位置 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `name` | `SKILL.md` 根级字段 | 是 | Skill 唯一标识符，须全小写+连字符（如 `invoice-parser`），不可与当前账号下任一 Skill 重名；名称变更即视为新 Skill。 |
|
||||
| `description` | `SKILL.md` 根级字段 | 是 | 决定 Skill 可被调用的关键语义描述。必须包含适用输入类型、支持操作、典型触发关键词、明确的不适用场景（见 [Skill (raw/application-user-guide/skill/introduction-to-skill.md)](../../raw/application-user-guide/skill/introduction-to-skill.md) 示例）。 |
|
||||
| ZIP 包大小 | 上传时校验 | — | ≤ 10 MB；超限将拒绝上传，且不提供分片或压缩提示。 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **添加 Skill 到智能体**：
|
||||
- 方式一：进入 [Skill 管理](https://bailian.console.aliyun.com/?tab=app#/skill)，点击目标 Skill 卡片 → **添加到智能体** → 选择应用；
|
||||
- 方式二：在目标智能体的**应用配置**页 → 左侧**技能**区域 → 点击 Skill 右侧 `+` → 从列表中勾选。
|
||||
1. **创建 Skill**
|
||||
- 官方 Skill：直接在 [Skill 管理](https://bailian.console.aliyun.com/?tab=app#/skill) 页面添加，无需配置。
|
||||
- 自定义 Skill：按规范编写 `SKILL.md`，打包全部依赖代码为 ZIP（根目录含 `SKILL.md`），通过控制台「组件 > Skill 管理 > 自定义 Skill」上传。
|
||||
|
||||
2. **测试效果**：在应用配置页右侧对话窗格中发送典型指令（如 `把附件里的销售数据按季度汇总成表格`），观察智能体是否正确调用 Skill 并返回预期结果（如生成 `.xlsx` 文件）。
|
||||
2. **添加到智能体**
|
||||
- 方式一：从 Skill 详情页点击「添加到智能体」，选择目标应用；
|
||||
- 方式二：进入智能体「应用配置」→「技能」区域，点击 Skill 右侧 `+` 添加。
|
||||
|
||||
3. **更新自定义 Skill**：修改本地 ZIP 包（含更新后的 `SKILL.md`）→ 在**自定义 Skill** 标签页重新上传同名包 → 审查通过后，所有已绑定该 Skill 的智能体自动升级。
|
||||
3. **测试与验证**
|
||||
- 在应用配置页右侧对话窗格中发送典型指令（如 `帮我把这张发票图片转成 Excel 表格`），观察是否触发对应 Skill 并正确返回文件；
|
||||
- 若未触发，优先检查 `description` 是否覆盖该场景关键词，再确认附件类型是否匹配。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- ZIP 包总大小上限为 **10 MB**，超限将导致上传失败；
|
||||
- `name` 字段全局唯一（同一账号下），重名上传会拒绝，需先删除旧版或改名；
|
||||
- `description` 中若未明确排除歧义场景（如“不处理扫描件 PDF”），可能导致误触发 —— 强烈建议按规范包含“不适用场景”说明；
|
||||
- 官方 Skill 的 `description` 不可编辑，其语义匹配逻辑由平台模型统一优化，用户无法干预；
|
||||
- 自定义 Skill 审查耗时约 2 分钟，失败时需根据错误提示（如 YAML 格式错误、`description` 缺失）修正后重传。
|
||||
- **版本更新**：官方 Skill 更新后，已添加的应用**自动生效最新版**；自定义 Skill 需重新上传同名 ZIP 包触发版本升级，旧版本不会被删除，但新调用默认使用最新版。
|
||||
- **安全限制**：自定义 Skill 运行于沙箱环境，禁止访问外网、读写本地磁盘（除解压临时目录）、执行系统命令（如 `os.system`）或加载动态链接库（`.so`/`.dll`）。
|
||||
- **调试盲区**：Skill 内部执行日志**不透出至智能体对话流或控制台实时日志**，仅可通过审查失败提示（如 `SKILL.md` 解析错误）或在 ZIP 包中预埋 `print()` 输出到标准输出（需配合平台日志审计权限查看）。
|
||||
- **触发不确定性**：即使 `description` 描述完备，模型仍可能因上下文歧义或附件元信息缺失（如无文件扩展名）导致漏触发或误触发——建议始终在生产环境部署前，用至少 5 种不同表述+3 类边界输入组合进行回归测试。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,42 +1,43 @@
|
||||
# start using
|
||||
|
||||
阿里云百炼平台提供零代码与高代码双路径，支持开发者快速构建、配置并发布智能体应用、工作流应用及高代码应用。本文档聚焦“开始使用”核心流程，涵盖模型/功能选型、关键参数配置、操作方式及重要限制，适用于首次接入的开发者。所有操作均基于控制台可视化界面或标准 API，无需预置基础设施。
|
||||
阿里云百炼平台提供零代码与低代码能力，帮助开发者快速构建基于大模型的智能应用。本文档聚焦“开始使用”路径，涵盖从创建首个智能体应用、配置知识库到发布上线的核心流程，并同步说明当前支持的功能范围、关键参数配置项、调用方式及重要限制。所有操作均可在控制台完成，无需部署后端服务。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **智能体应用（Agent 2.0）**：默认支持 `qwen-max`、`qwen-plus`、`qwq-plus`、`qwq-32b` 及 `deepseek-*` 系列模型；自 2025 年 12 月起，新版智能体统一将知识库、MCP 作为可规划调用的工具，并完整展示思考链与工具执行过程 [0代码构建私有知识问答应用](../../raw/application-user-guide/start-using/build-knowledge-base-qa-assistant-without-coding.md)。
|
||||
- **多模态能力**：`qwen-vl-plus-latest`、`qwen-vl-plus-2025-01-25` 支持图文理解与音视频内容解析；知识库节点支持文档、图片、表格、音视频等多种格式输入 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **知识库类型**：分为**文档型**（非结构化）、**数据型**（结构化，支持 RDS/MySQL/DMS 同步）和**图片型**三类；自 2025 年 9 月起创建流程已按此分类简化 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **[长期记忆](../concepts/long-term-memory.md)**：新版[长期记忆](../concepts/long-term-memory.md)（2.0）提供自动信息提取、语义检索、用户画像管理等能力，API 兼容多应用共享同一记忆库 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **基础模型支持**：智能体应用支持 `qwen-max`、`qwq-plus`、`qwq-32b`、`qwen-vl-plus-latest` 等主流模型；工作流应用额外支持 DeepSeek 系列模型（如 DeepSeek-V2、DeepSeek-Coder）[应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **知识库类型**：支持三类知识库——**文档型**（PDF/DOCX/HTML/Excel 等）、**数据型**（RDS、DMS、自建 MySQL 表）、**图片/音视频型**（支持上传 MP4、MP3、JPG/PNG 及自动语音转写、图文解析）[应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **增强能力**：
|
||||
- [多模态](../concepts/multi-modal.md)回复增强（需开启并关联含图像/音视频的知识库）；
|
||||
- [长期记忆](../concepts/long-term-memory.md)（新 API 版本，支持多应用共享、自动信息提取与语义检索）；
|
||||
- MCP（Model Calling Protocol）服务集成，可调用预置或自定义外部工具 [0代码构建私有知识问答应用](../../raw/application-user-guide/start-using/build-knowledge-base-qa-assistant-without-coding.md)。
|
||||
|
||||
> **注意**：文档 1 中提及的“Assistant API（下线中）”已明确废弃，不建议新项目采用；应优先使用智能体应用或工作流应用的标准化调用接口。
|
||||
> **注意**：文档 1 中提及的“Assistant API（下线中）”已明确废弃，不建议新项目采用；当前推荐路径为智能体应用（Agent 2.0）或工作流应用，其能力覆盖更全、维护持续 [0代码构建私有知识问答应用](../../raw/application-user-guide/start-using/build-knowledge-base-qa-assistant-without-coding.md)。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **知识库检索参数**：可通过“检索配置”调整 `初步向量检索TopK` 和 `初步关键词检索TopK`，降低送入排序模型的 [Token](../concepts/token.md) 量以控制成本（自 2026 年 1 月 6 日起生效）[应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **知识库权重**：当智能体应用关联多个知识库时，可为每个知识库设置权重，系统优先召回高权重知识源的内容（2025 年 4 月上线）[应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **Prompt 配置**：System Prompt 定义角色与任务边界，建议明确限定领域范围（如“你是一位阿里云百炼手机导购…”），避免泛化回答 [0代码构建私有知识问答应用](../../raw/application-user-guide/start-using/build-knowledge-base-qa-assistant-without-coding.md)。
|
||||
- **多模态回复增强**：开关位于智能体应用“检索配置”中，开启后启用知识库内图表/图像的视觉理解能力（2025 年 3 月上线）[应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **知识库检索参数**：可在智能体应用的「检索配置」中调整 `初步向量检索TopK` 和 `初步关键词检索TopK`，降低召回 [Token](../concepts/token.md) 量以优化成本 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **知识库权重**：当一个智能体应用关联多个知识库时，支持为每个知识库设置权重值（1–10），系统按权重优先召回高相关性内容 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **Prompt 配置**：System Prompt 定义角色与任务边界，建议明确限定领域（如“你是一位阿里云百炼手机导购…”），避免泛化回答；同时支持 FewShot Prompt 样例库提升准确性 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **创建应用**：访问 [应用管理](https://bailian.console.aliyun.com/?tab=app#/app-center)，选择“智能体应用” → “立即创建”，填写名称并选择模型（推荐 `qwen-max` 或 `qwq-plus`）。
|
||||
2. **配置 Prompt 与交互元素**：设置 System Prompt、欢迎语及预设问题，提升首屏引导效果 [0代码构建私有知识问答应用](../../raw/application-user-guide/start-using/build-knowledge-base-qa-assistant-without-coding.md)。
|
||||
3. **构建知识库**：
|
||||
- 文档型：直接上传 `.docx`/`.pdf`/`.xlsx`/`.html`/音视频文件（2025 年 9 月起支持离线 HTML 与 Excel 导入）；
|
||||
- 数据型：从 RDS、DMS 或自建 MySQL 表同步结构化数据；
|
||||
- 创建时可选“智能切分”策略，并启用调试面板实时验证召回效果（2025 年 9 月上线）[应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
4. **绑定与发布**：在应用配置页 → “技能” → “知识库” → 添加已创建的知识库 → 点击“发布”。
|
||||
5. **调用方式**：
|
||||
1. **创建智能体应用**：访问 [应用管理](https://bailian.console.aliyun.com/?tab=app#/app-center)，点击「创建应用」→「智能体应用」→ 设置名称、选择模型（推荐 `qwen-max` 或 `qwq-plus`）、填写 System Prompt 与欢迎语/预设问题。
|
||||
2. **构建知识库**：
|
||||
- 文档型：直接在知识库创建页上传文件（支持 DOCX、PDF、HTML、Excel、音视频等），选择「智能切分」策略；
|
||||
- 数据型：选择「结构化知识库」，配置 RDS/DMS/MySQL 数据源表；
|
||||
- 图片/音视频型：上传媒体文件，系统自动执行 ASR、OCR、VL 模型解析。
|
||||
3. **绑定与发布**：进入应用配置页 → 「技能」→ 「知识库」→ 点击 `+` 添加已创建的知识库 → 确认后点击「发布」。
|
||||
4. **调用方式**：
|
||||
- 控制台内测：右侧对话框直接提问；
|
||||
- API 调用：支持同步（`Responses API`）与异步（`background=true`）两种模式，兼容 OpenAI SDK 接口规范（2025 年 11 月上线）[应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- API 调用：支持同步（`Responses API`）与异步（`background=true` + Task ID 查询）两种模式 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)；
|
||||
- 外部集成：通过 H5/APP SDK、钉钉/微信机器人、MCP SDK 等渠道嵌入。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **计费变更**：知识库服务自 2026 年 1 月 4 日起正式商业化，费用 = 规格费 + 模型调用费；免费额度仅限部分模型，需前往 [模型广场](https://bailian.console.aliyun.com/cn-beijing?tab=model#/model-market/all) 查看详情 [0代码构建私有知识问答应用](../../raw/application-user-guide/start-using/build-knowledge-base-qa-assistant-without-coding.md)。
|
||||
- **模型能力边界**：QwQ 系列模型虽具备强推理能力，但**不支持[插件](../concepts/plugin.md)、流程编排及音视频交互能力**（2025 年 4 月说明）；若需多步骤自动化，应选用工作流应用 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **知识库时效性**：上传文档后需等待 1–6 分钟完成解析（非结构化）或 1–2 分钟（结构化），期间不可用于检索 [0代码构建私有知识问答应用](../../raw/application-user-guide/start-using/build-knowledge-base-qa-assistant-without-coding.md)。
|
||||
- **权限与分账**：子账号可独立开通知识库，通过标签实现分账管理（2026 年 1 月上线），但需主账号授权对应 RAM 权限 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **计费变更**：知识库服务自 2026 年 1 月 4 日起正式商业化，费用 = 规格费 + 模型调用费；免费额度仅限部分模型，详情见 [知识库计费说明](https://help.aliyun.com/zh/model-studio/billing-for-knowledge-base) [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **模型能力边界**：QwQ 系列模型虽推理能力强，但**不支持插件、音视频交互及流程编排能力**，仅适用于纯文本深度推理场景 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **调试依赖**：知识库调试需使用新版「调试面板」（编辑智能体应用时可见），旧版无实时召回验证能力；若未启用该面板，建议先升级至 Agent 2.0 架构 [应用功能动态](../../raw/application-user-guide/start-using/application-release-notes.md)。
|
||||
- **[文件处理](../concepts/file-processing.md)限制**：单次上传文档大小上限为 100 MB；音视频文件最长支持 2 小时，超长内容将被截断处理。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,35 +1,48 @@
|
||||
# test 1
|
||||
|
||||
`test 1` 是阿里云百炼平台面向开发者提供的核心计费与资源管理主题，涵盖模型调用、训练、部署的费用结构、免费额度机制及成本优化工具。本文档整合了新人免费额度、模型调用价格、节省计划与资源包、账单查询及模型训练/部署计费五大维度，聚焦华北2（北京）地域的主流文本生成模型（如千问系列），明确各环节的适用范围、生效逻辑与关键约束。所有计费行为均以实际调用结束后的出账为准，开发者需结合免费额度、节省计划与资源包的抵扣优先级进行成本规划。
|
||||
`test 1` 是阿里云百炼平台面向开发者提供的核心计费与成本管理主题，涵盖模型调用、训练、部署的定价规则，以及免费额度、节省计划、资源包等成本优化机制。本文档聚焦于实时推理（模型调用）场景的通用计费逻辑，不涉及模型训练与部署的专用计费模型（详见[模型训练与部署计费](../../raw/model-user-guide/test-1/model-training-and-deployment-billing.md)），并明确区分了免费额度、按量付费及各类优惠方案的适用边界与抵扣顺序。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
- **支持免费额度的模型**：仅限华北2（北京）地域的实时推理调用，包括 `qwen-max`、`qwen3.7-plus`、`qwen3.6-plus` 等千问系列模型（含带日期后缀的快照版本，如 `qwen3.7-plus-2026-05-26`），以及部分万相、CosyVoice 模型。其他地域（如美国、新加坡、德国）模型**不享有免费额度**，详见[新人免费额度](../../raw/model-user-guide/test-1/new-free-quota.md)。
|
||||
- **支持阶梯计费的模型**：千问Max、千问Plus 系列在华北2（北京）等地域按输入 [Token](../concepts/token.md) 区间分档定价（如 `0<Token≤128K`、`128K<Token≤256K`），单价随用量递增；Batch 调用可享实时推理价格 50% 折扣，但与上下文缓存折扣互斥 [模型调用价格](../../raw/model-user-guide/test-1/model-pricing.md)。
|
||||
- **支持模型训练与部署的模型**：千问、千问VL、万相、CosyVoice、DeepSeek、GLM 等均支持训练与部署，但训练仅限华北2（北京）地域（CosyVoice 明确限定），部署则覆盖多地域 [模型训练与部署计费](../../raw/model-user-guide/test-1/model-training-and-deployment-billing.md)。
|
||||
- **支持模型**：覆盖千问（Qwen）全系列（Max、Plus、Flash、Coder、VL、Embedding、Rerank 等）、DeepSeek、GLM、Kimi、万相（WanX）、CosyVoice 等主流文本、[多模态](../concepts/multi-modal.md)、语音、图像、视频模型。
|
||||
- **核心功能**：
|
||||
- 实时推理（同步/流式调用）
|
||||
- Batch 调用（文件输入，价格为实时推理的 50%）
|
||||
- 上下文缓存（显式/隐式，计费单价独立于标准输入，详见[上下文缓存文档](https://help.aliyun.com/zh/model-studio/context-cache)）
|
||||
- Function Calling、网页抓取等原生工具调用（费用可被 AI 通用型节省计划抵扣）
|
||||
|
||||
> **注意**：文档 5 中 `qwen3.7-max` 在华北2（北京）标注“当前能力等同于 `qwen3.7-max-2026-05-20`”，而文档 2 的部署计费表中列出 `qwen3.7-max-2026-05-20`，但文档 5 的价格表未包含该精确 ID 的单价。开发者应以控制台实时展示或[模型调用价格](../../raw/model-user-guide/test-1/model-pricing.md)中最新快照版本为准，避免使用已归档的别名 ID。
|
||||
> **注意**：文档 5 中“千问Max”表格将 `qwen3.7-max` 标注为“当前能力等同于 `qwen3.7-max-2026-05-20`”，但文档 2 的部署计费表中仅列出 `qwen3.7-max-2026-05-20`，未提及其别名映射关系；实际调用应以控制台或 API 返回的 `model` 字段为准，避免依赖别名。该不一致需以[模型调用价格](../../raw/model-user-guide/test-1/model-pricing.md)中明确列出的 Model ID 为准。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **免费额度参数**：默认 100 万 [Token](../concepts/token.md)/模型，有效期 90 天（自开通/模型发布/申请通过日起算，以较晚者为准）；主账号与 RAM 子账号共享额度，不同模型（含快照版本）额度独立 [新人免费额度](../../raw/model-user-guide/test-1/new-free-quota.md)。
|
||||
- **[Token](../concepts/token.md) 计费参数**：输入/输出 Token 单价单位为“每百万 Token”，实际费用 = (输入 Token 数 / 1,000,000) × 输入单价 + (输出 Token 数 / 1,000,000) × 输出单价；Batch 调用单价为实时推理单价的 50% [模型调用价格](../../raw/model-user-guide/test-1/model-pricing.md)。
|
||||
- **部署计费参数**：预置吞吐模式按 TPM（Tokens Per Minute）计费，公式为 `费用 = 使用时长 × (输入 TPM 单价 × 输入 TPM + 输出 TPM 单价 × 输出 TPM)`；模型单元模式按 `费用 = 使用时长（小时）× 模型单元数量 × 小时单价` 计算，最小计费单位为分钟 [模型训练与部署计费](../../raw/model-user-guide/test-1/model-training-and-deployment-billing.md)。
|
||||
- **节省计划参数**：AI 通用型节省计划按月承诺消费金额（1000 元起）和周期（3/6/12/24 个月）生效，抵扣顺序为免费额度 > 资源包 > 其他模型节省计划 > AI 通用型节省计划 > 按量付费 [节省计划与资源包](../../raw/model-user-guide/test-1/savings-plan-and-resource-package.md)。
|
||||
- **计费维度**：以 [Token](../concepts/token.md) 为基本单位，分 `input_token` 和 `output_token` 单独计费。
|
||||
- **阶梯计费**：部分模型（如 `qwen3-max`、`qwen3.7-plus`）按单次请求的输入 [Token](../concepts/token.md) 总量分档定价，所有 [Token](../concepts/token.md) 均按所处最高档单价结算（例如输入 100K Token 落入 32K–128K 档，则全部 100K 按该档单价计费）。
|
||||
- **地域差异**：同一模型在不同地域（华北2、美国、新加坡、德国、日本）价格不同，且**仅华北2（北京）地域模型享有新人免费额度**，其他地域无此权益 [原文标题](../../raw/model-user-guide/test-1/new-free-quota.md)。
|
||||
- **免费额度参数**：每个模型（含不同快照版本，如 `qwen-max` 与 `qwen-max-2026-05-17`）独立享有 100 万 Token 免费额度，有效期 90 天（自开通/模型发布/申请通过日起较晚者计算）。
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **启用免费额度**：开通百炼服务后自动发放，无需额外操作；调用时系统自动优先抵扣，使用通用 API Key（非 Token Plan/Coding Plan 专属 Key）即可生效 [新人免费额度](../../raw/model-user-guide/test-1/new-free-quota.md)。
|
||||
- **配置节省计划**：购买 AI 通用型节省计划后立即生效，自动抵扣模型调用、工具调用、批量推理等费用（不含模型训练、部署、联网搜索[插件](../concepts/plugin.md)）；若开启“免费额度用完即停”，需手动关闭该开关才能触发节省计划抵扣 [节省计划与资源包](../../raw/model-user-guide/test-1/savings-plan-and-resource-package.md)。
|
||||
- **查询与监控**：通过控制台[费用概览](https://bailian.console.aliyun.com/?tab=model#/costing-balance)查看当月总消费；账单明细需在[账单详情](https://usercenter2.aliyun.com/finance/expense-report/expense-detail)中筛选“大模型服务平台百炼”，解析 `实例 ID（出账粒度）` 字段（格式：`ApiKeyID;业务空间ID;模型名称;输入/输出类型;调用渠道;免费额度用完即停标识`）定位具体模型与调用渠道 [账单查询与成本管理](../../raw/model-user-guide/test-1/bill-query-and-cost-management.md)。
|
||||
- **停止计费**：删除 API Key 防止意外调用；下线已部署模型终止按时长计费；退订预付费实例需在[退订管理](https://usercenter2.aliyun.com/refund/refund)页面操作 [账单查询与成本管理](../../raw/model-user-guide/test-1/bill-query-and-cost-management.md)。
|
||||
- **调用流程**：使用通用 API Key（非 Token Plan/Coding Plan 专属 Key）发起 HTTP 请求，系统自动按以下优先级抵扣费用：**免费额度 > 资源包 > 其他模型节省计划 > AI 通用型节省计划 > 按量付费** [原文标题](../../raw/model-user-guide/test-1/savings-plan-and-resource-package.md)。
|
||||
- **启用免费额度**：无需额外配置，首次开通百炼后，在华北2（北京）地域调用支持的模型即自动生效。专属 API Key 不消耗免费额度，须改用通用 Key [原文标题](../../raw/model-user-guide/test-1/new-free-quota.md)。
|
||||
- **成本优化选型**：
|
||||
- 高频、跨模型调用：首选 [AI 通用型节省计划](../../raw/model-user-guide/test-1/savings-plan-and-resource-package.md)，承诺月消费额换取最高 5.3 折。
|
||||
- 单一模型稳定用量：可选对应模型的“其他模型节省计划”或“资源包”。
|
||||
- 短期、不确定用量：直接按量付费，配合“免费额度用完即停”功能防意外扣费。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **免费额度限制**：仅抵扣实时推理费用，**不支持 Batch 调用、模型训练、模型部署、自定义模型（调优后/已部署）**；额度过期后自动作废，不可补发或重置；全新未认证用户额度耗尽后直接返回错误码 `AllocationQuota.FreeTierOnly`，需认证并充值方可继续 [新人免费额度](../../raw/model-user-guide/test-1/new-free-quota.md)。
|
||||
- **地域与模型绑定限制**：免费额度、CosyVoice 训练、部分模型部署仅限华北2（北京）；美国、新加坡等地域模型虽可调用，但无免费额度且单价不同（如 `qwen3.7-plus-us` 单价高于国内版） [模型调用价格](../../raw/model-user-guide/test-1/model-pricing.md)。
|
||||
- **抵扣逻辑冲突**：若同时开启“免费额度用完即停”与节省计划，免费额度耗尽后服务将停止，节省计划无法触发抵扣；必须关闭“免费额度用完即停”才能启用节省计划 [节省计划与资源包](../../raw/model-user-guide/test-1/savings-plan-and-resource-package.md)。
|
||||
- **欠费影响**：账户欠费时，**即使免费额度、节省计划、资源包仍有剩余，所有按量付费服务均暂停**；Coding Plan/Token Plan 套餐额度不受影响，但自动续费会失败 [账单查询与成本管理](../../raw/model-user-guide/test-1/bill-query-and-cost-management.md)。
|
||||
- **免费额度限制**：
|
||||
- 仅抵扣**实时推理**费用，**不支持** Batch 调用、模型调优、模型部署、自定义模型（调优后/已部署） [原文标题](../../raw/model-user-guide/test-1/new-free-quota.md)。
|
||||
- 主账号与 RAM 子账号共享额度，但不同模型额度完全独立，不会自动切换。
|
||||
- 免费额度耗尽后，全新未认证用户将返回错误码 `AllocationQuota.FreeTierOnly` 并停止服务；已认证用户若未开启“免费额度用完即停”，将直接按量扣费。
|
||||
|
||||
- **账户状态影响**：
|
||||
- **账户欠费时，即使模型仍有免费额度也无法调用**，必须结清欠费才能恢复服务 [原文标题](../../raw/model-user-guide/test-1/bill-query-and-cost-management.md)。
|
||||
- 模型部署（按时长计费）与 API 调用（按 Token 计费）是两个独立计费项：部署状态为“运行中”即开始计费，与是否发生 API 调用无关。
|
||||
|
||||
- **账单与监控**：
|
||||
- 推理账单分钟级出账（2–10 分钟），训练/批量/知识库账单小时级出账。
|
||||
- 账单中“实例 ID（出账粒度）”字段以分号 `;` 分隔，格式为 `ApiKeyID;业务空间ID;模型名称;输入/输出类型;调用渠道;免费额度用完即停标识`，是定位费用归属的关键依据 [原文标题](../../raw/model-user-guide/test-1/bill-query-and-cost-management.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
|
||||
@@ -1,77 +1,66 @@
|
||||
# token plan guide
|
||||
|
||||
[Token](../concepts/token.md) Plan 是阿里云百炼推出的 AI 大模型订阅服务，以 Credits 为统一计量单位，支持文本、多模态生成及 Harness 工具调用，适配主流 AI 编程与智能体工具。服务目前仅支持华北2（北京）地域，个人版与团队版独立计费、额度不共享，且均需通过专属 API Key 与 Base URL 接入。[原文标题](../../raw/model-user-guide/token-plan-guide/token-plan-overview.md) 明确指出其核心定位为“AI 编程和智能体工具的统一订阅入口”。
|
||||
[Token](../concepts/token.md) Plan 是阿里云百炼推出的 AI 大模型订阅服务，以 Credits 统一计量，支持多种 AI 编程和智能体工具。该服务分为个人版和团队版，分别面向个人开发者与企业团队，提供模型调用、[多模态](../concepts/multi-modal.md)生成及 Harness 工具等能力，所有功能当前仅限华北2（北京）地域使用。
|
||||
|
||||
## 支持的模型与功能
|
||||
## 支持的模型/功能
|
||||
|
||||
[Token](../concepts/token.md) Plan 支持覆盖推理、视觉理解、图像/视频生成、语音合成等能力的多模态模型，并集成联网搜索、代码解释器等 Harness 工具。
|
||||
[Token](../concepts/token.md) Plan 支持文本生成、图像生成、视频生成、语音合成等[多模态](../concepts/multi-modal.md)模型，以及联网搜索、代码解释器、网页抓取等 Harness 工具。具体模型列表详见 [Token Plan 个人版](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-overview.md) 和 [Token Plan 团队版](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-overview.md) 的官方文档。
|
||||
|
||||
- **模型范围**：
|
||||
- 文本与推理：`qwen3.8-max-preview`（预览版，享限时 1 折+夜间 0.2 折）、`qwen3.7-plus`、`glm-5.2`、`deepseek-v4-pro`、`kimi-k2.5` 等；
|
||||
- 图像生成：`wan2.7-image`、`qwen-image-2.0-pro`；
|
||||
- 视频生成：`happyhorse-1.1-t2v`、`happyhorse-1.1-r2v`；
|
||||
- 语音合成：`qwen-audio-3.0-tts-plus`。
|
||||
完整列表见 [原文标题](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-overview.md) 与 [原文标题](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-overview.md)。
|
||||
- **核心模型**：qwen3.8-max-preview（预览版，享限时 1 折+夜间 0.2 折）、qwen3.7-plus、qwen3.6-flash、wan2.7-image、happyhorse-1.1-t2v、qwen-audio-3.0-tts-plus 等。
|
||||
- **Harness 工具**：仅 qwen3.7 及以上系列模型原生支持，包括 `web_search`、`code_interpreter`、`t2i_search`、`i2i_search`、`web_extractor`；调用按成功次数抵扣 Credits [接入 Harness 工具](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/token-plan-harness-tool.md)。
|
||||
- **[多模态](../concepts/multi-modal.md)生成**：图像、视频、语音模型需通过工具扩展机制（如 Slash Command、Skill、Agent）接入，不可直接通过 OpenAI/Anthropic 兼容 Base URL 调用 [接入多模态生成模型](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/token-plan-multimodal-gen.md)。
|
||||
- **视觉理解**：qwen3.7-plus、qwen3.6-plus、kimi-k2.5 等模型原生支持；glm-5、MiniMax-M2.5 等纯文本模型需通过 Skill 或 Agent 辅助实现 [添加视觉理解能力](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/add-vision-skill.md)。
|
||||
|
||||
- **Harness 工具**：
|
||||
支持 `web_search`、`code_interpreter`、`t2i_search`、`i2i_search`、`web_extractor`，仅 `qwen3.7-plus`、`qwen3.8-max-preview` 等 Qwen 系列模型原生支持，调用按成功次数抵扣 Credits。详见 [原文标题](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/token-plan-harness-tool.md)。
|
||||
|
||||
- **视觉理解**：
|
||||
`qwen3.7-plus`、`qwen3.6-plus`、`kimi-k2.5` 等模型原生支持图片输入；对 `glm-5` 等纯文本模型，可通过 Skill/Agent 封装视觉模型实现间接支持（如用 `qwen3.7-plus` 分析图片后返回结果）。[原文标题](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/add-vision-skill.md) 提供了具体配置示例。
|
||||
|
||||
> **注意**：文档 12（Coding Plan）中声明 `qwen3-coder-next` 和 `qwen3-coder-plus` 为 Coding Plan 支持模型，但所有 [Token](../concepts/token.md) Plan 文档（1、2、10）均未将其列入支持列表，且明确限定模型 ID 必须精确匹配白名单。因此，`qwen3-coder-next` 和 `qwen3-coder-plus` **不支持** Token Plan，开发者应严格依据 Token Plan 文档中的模型 ID 列表选用。
|
||||
> **注意**：文档 13（Coding Plan概述）中声明“Lite 套餐已于 2026 年 3 月 20 日起停止新购”，而文档 1 中明确指出“推荐使用 [Token](../concepts/token.md) Plan，支持更多模型和 Harness 工具”。二者定位不同，Coding Plan 已逐步被 Token Plan 替代，开发者应优先选用 Token Plan。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **Credits 计费机制**：
|
||||
单次调用消耗由模型类型、输入/输出 Token 数、思考模式启用状态及 Harness 工具调用共同决定，实际消耗以控制台用量明细为准。例如 `qwen3.6-plus` 一次请求可能消耗约 3.18 Credits（含输入、缓存、输出 tokens）。
|
||||
|
||||
- **额度结构**：
|
||||
- **个人版**：双层窗口限额——**5 小时限额**（自首次调用起滚动计时）与**7 天限额**（自首次调用起固定窗口），任一触顶即暂停服务。Lite/Standard/Pro 套餐对应额度分别为 (700, 2500) / (3000, 10000) / (12000, 40000) Credits。
|
||||
- **团队版**：**月度总额度制**，无窗口限制。标准/高级/尊享坐席分别为 25,000 / 100,000 / 250,000 Credits/坐席/月，未用完额度不结转。
|
||||
|
||||
- **并发与 Agent 限制**：
|
||||
个人版 Lite/Standard/Pro 套餐分别支持 1–2 / 3–4 / 6–8 个 Agent 并发；团队版无显式并发上限，依托多租户隔离架构保障高峰期不排队。
|
||||
- **Credits 计费机制**：单次消耗由模型类型、Token 用量、思考模式及工具调用动态决定，实际消耗以控制台用量明细为准。
|
||||
- **限额机制**：
|
||||
- *个人版*：采用双层窗口限额——**每 5 小时**和**每 7 天**独立计时，任一触顶即暂停服务；额度不结转，可购买用量包补充或手动重置 [Token Plan 个人版](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-overview.md)。
|
||||
- *团队版*：采用**月度总额度制**，无窗口限制；各坐席额度按月重置，未用完不结转；超出后可购买共享用量包（625,000 Credits/个，有效期 1 个月）[Token Plan 团队版](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-overview.md)。
|
||||
- **并发能力**：个人版 Lite/Standard/Pro 套餐分别支持 1–2 / 3–4 / 6–8 个 Agent 并发；团队版无显式并发限制，依托多租户隔离架构保障高峰期不排队。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **订阅与凭证获取**：
|
||||
在华北2（北京）地域的百炼控制台完成订阅。API Key 以 `sk-sp-` 开头，Base URL 固定为：
|
||||
- OpenAI 兼容：`https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`
|
||||
- Anthropic 兼容：`https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic`
|
||||
（注意：与 Coding Plan 的 `coding.dashscope.aliyuncs.com` 及通用 API 的 `dashscope.aliyuncs.com` 完全隔离）
|
||||
|
||||
2. **接入 AI 工具**：
|
||||
将上述 API Key 与 Base URL 配置至 Cursor、Claude Code、Qwen Code、Qoder 等兼容工具。[原文标题](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-quick-start.md) 与 [原文标题](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-quickstart.md) 提供了详细步骤。
|
||||
|
||||
3. **扩展能力接入**：
|
||||
- **多模态生成**（图像/视频/语音）：必须通过工具的扩展机制（如 Claude Code 的 Slash Command、Qwen Code 的 Skill）调用独立 API 接口，不可直接使用文本模型 Base URL。[原文标题](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/token-plan-multimodal-gen.md) 给出完整配置模板。
|
||||
- **联网搜索（MCP）**：需额外开通百炼通用 API Key（`sk-xxx`）认证的 MCP 服务，Endpoint 为 `https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp`，与 Token Plan API Key 分离使用。[原文标题](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/web-search-mcp.md) 说明此关键区别。
|
||||
1. **地域与订阅**：必须将百炼控制台地域切换至**华北2（北京）**，再访问对应购买页完成订阅。
|
||||
2. **API Key 与 Base URL**：
|
||||
- API Key 以 `sk-sp-` 开头，仅限 Token Plan 专属使用，与通用 API Key（`sk-`）及 Coding Plan Key 完全隔离。
|
||||
- Base URL 分协议：
|
||||
- OpenAI 兼容：`https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`
|
||||
- Anthropic 兼容：`https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic`
|
||||
3. **工具接入**：支持 Cursor、Claude Code、Qwen Code、Qoder、OpenClaw 等主流工具，配置 API Key 和 Base URL 即可启用 [快速开始（个人版）](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-quick-start.md) 和 [快速开始（团队版）](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-quickstart.md)。
|
||||
4. **高级能力接入**：
|
||||
- Harness 工具：切换至支持模型后直接提问，模型自动调用。
|
||||
- 多模态模型：需在工具中配置 Skill/Slash Command/Agent，调用独立接口（如 `/text-to-image`）。
|
||||
- 联网搜索 MCP：需额外开通百炼通用 API Key（`sk-`）驱动的 MCP 服务，与 Token Plan 专属 Key 分离 [联网搜索](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/web-search-mcp.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域限制**：强制要求华北2（北京）地域，控制台地域切换失败将导致购买或调用异常。
|
||||
- **使用场景限制**：严禁用于自动化脚本、后台定时任务、生产环境后端服务等非交互式场景；仅限在官方指定工具（如 Cursor、Claude Code）中交互式使用。违规可能导致 API Key 封禁。
|
||||
- **账号规范**：个人版禁止共享；团队版 API Key 与席位绑定，仅限分配成员本人使用。
|
||||
- **数据政策**：个人版数据可用于服务改进；团队版明确承诺**不使用对话数据训练模型**。
|
||||
- **额度补充**：个人版可购用量包（20,000 Credits/100 元，无窗口限制）；团队版可购共享用量包（625,000 Credits/5000 元，跨坐席共享）。
|
||||
- **模型时效性**：`qwen3.8-max-preview` 为预览模型，能力持续迭代，预览结束后可能下线或替换，不保证长期可用。
|
||||
- **地域限制**：所有 Token Plan 功能仅在华北2（北京）可用，跨地域调用将失败。
|
||||
- **使用范围限制**：仅限交互式开发工具（如 Claude Code、Cursor）中使用，**严禁用于自动化脚本、应用后端或批量调用**；违规可能导致订阅暂停或 API Key 封禁 [Token Plan 个人版](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-overview.md)。
|
||||
- **数据安全**：团队版承诺不使用对话数据训练模型；个人版则授权用于服务改进与模型优化。
|
||||
- **账号规范**：API Key 不可共享；团队版需通过成员管理分配席位，RAM 用户需主账号授予 `AliyunTokenPlanFullAccess` 及 `AliyunBSSReadOnlyAccess` 权限。
|
||||
- **升级与退订**：
|
||||
- 个人版支持升配（补差价），不支持降配；暂不支持退订。
|
||||
- 团队版支持加购/升级席位，不支持降配；退订席位后 API Key 和 Base URL 将变更，需重新配置。
|
||||
- **额度重置**：个人版可手动重置 5 小时/7 天限额；团队版仅支持等待月度重置或购买共享用量包。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [Token Plan 概述](../../raw/model-user-guide/token-plan-guide/token-plan-overview.md)
|
||||
- [概述](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-overview.md)
|
||||
- [快速开始](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-quick-start.md)
|
||||
- [常见问题](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-faq.md)
|
||||
- [接入 Harness 工具](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/token-plan-harness-tool.md)
|
||||
- [接入多模态生成模型](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/token-plan-multimodal-gen.md)
|
||||
- [添加视觉理解能力](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/add-vision-skill.md)
|
||||
- [联网搜索](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/web-search-mcp.md)
|
||||
- [快速开始](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-quickstart.md)
|
||||
- [概述](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-overview.md)
|
||||
- [团队管理](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-management.md)
|
||||
- [快速开始](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-quickstart.md)
|
||||
- [常见问题](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-faq.md)
|
||||
- [快速开始](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-quick-start.md)
|
||||
- [概述](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-overview.md)
|
||||
- [常见问题](../../raw/model-user-guide/token-plan-guide/token-plan-personal/token-plan-personal-faq.md)
|
||||
- [接入多模态生成模型](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/token-plan-multimodal-gen.md)
|
||||
- [接入 Harness 工具](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/token-plan-harness-tool.md)
|
||||
- [添加视觉理解能力](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/add-vision-skill.md)
|
||||
- [联网搜索](../../raw/model-user-guide/token-plan-guide/token-plan-best-practice/web-search-mcp.md)
|
||||
- [Coding Plan概述](../../raw/model-user-guide/token-plan-guide/coding-plan-guide/coding-plan.md)
|
||||
- [常见问题](../../raw/model-user-guide/token-plan-guide/coding-plan-guide/coding-plan-faq.md)
|
||||
- [常见问题](../../raw/model-user-guide/token-plan-guide/token-plan-team-edition/token-plan-team-faq.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,61 +1,89 @@
|
||||
# use cases
|
||||
|
||||
百炼平台提供覆盖文本、图像、视频、语音、多模态及智能体等全栈AI能力的生产级用例，支持从模型调用、Prompt工程、RAG构建到实时音视频交互的完整开发链路。所有方案均基于函数计算等云服务开箱即用，兼顾开发效率与生产稳定性。
|
||||
百炼平台提供覆盖文本、图像、视频、语音及[多模态](../concepts/multi-modal.md)的全栈AI能力，支持从简单Prompt调用到复杂工作流编排的多样化应用场景。开发者可基于预置模型快速构建应用，也可通过自定义训练、RAG、Agent编排等技术深度适配业务需求。所有能力均通过统一API接口和控制台提供，兼顾开箱即用性与工程可控性。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
百炼支持阿里云自研模型（如 Qwen 系列、Wan2.7、HappyHorse、qwen3.5-omni-plus-realtime）及第三方直供模型（如 DeepSeek、Kimi、GLM、MiniMax、MiMo、Stepfun、Vidu），覆盖文本生成、多模态理解、文生图/文生视频、图生视频、文档转视频、深度研究、AI教学辅学等场景。
|
||||
第三方模型接入需注意地域限制：多数仅支持华北2（北京）地域，且需使用业务空间专属域名 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com` 以获得更优性能与稳定性 [DeepSeek-硅基流动](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/siliconflow-deepseek-api.md)。
|
||||
> **注意**：多个第三方模型文档（[DeepSeek-阿里云](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/deepseek-api.md)、[Kimi](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/kimi-api.md)、[GLM](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/glm.md)、[MiniMax](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/minimax-api.md)）均明确标注了模型下架时间（2026年7月或10月），并统一推荐迁移至 `qwen3.7-plus`/`qwen3.7-max`/`qwen3.6-flash`，该迁移路径已在各文档中强提示。
|
||||
百炼平台支持多种模型类型与生成能力，涵盖通用大语言模型、[多模态](../concepts/multi-modal.md)模型、视觉生成模型及第三方直供模型：
|
||||
|
||||
- **文本模型**：Qwen系列（如 `qwen3.7-plus`、`qwen3.7-max`）、DeepSeek（`siliconflow/deepseek-v3.2`、`vanchin/deepseek-v4-pro`）、Kimi（`kimi/kimi-k3`）、GLM（`ZHIPU/GLM-5.2`）、MiniMax（`MiniMax/MiniMax-M2.7`）、MiMo（`xiaomi/mimo-v2.5-pro`）、Step（`stepfun/step-3.7-flash`）等。[DeepSeek-硅基流动](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/siliconflow-deepseek-api.md) 和 [Kimi-月之暗面](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/kimi-api-by-moonshot-ai.md) 文档详细说明了各供应商模型的接入方式与思考模式控制参数（如 `enable_thinking` 或 `reasoning_effort`）。
|
||||
|
||||
- **视觉模型**：万相系列（`wan2.7` 图像/视频生成）、Qwen-VL系列（`qwen3-vl-plus` 用于解题与批改）、HappyHorse 视频生成模型。其中，[HappyHorse 打造一站式影视创作平台](../../raw/model-user-guide/use-cases/infinite-canvas.md) 展示了如何融合 Wan2.7 与 HappyHorse 构建节点式无限画布创作流。
|
||||
|
||||
- **[多模态](../concepts/multi-modal.md)与实时交互**：`qwen3.5-omni-plus-realtime` 支持 WebRTC 实时音视频通话；多模态交互套件（multimodal-dialog）面向硬件终端提供低延迟交互能力。
|
||||
|
||||
- **增强与编排能力**：RAG（基于 LlamaIndex 集成知识库）、Agent（自主决策与 Function Call）、工作流（可视化节点编排）、深度研究（Qwen-Deep-Research 自动化情报分析）。
|
||||
|
||||
> **注意**：多个第三方模型文档（如 [DeepSeek-阿里云](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/deepseek-api.md)、[GLM](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/glm.md)、[MiniMax](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/minimax-api.md)）均声明部分旧版本模型将于 2026 年下架，并统一推荐迁移至 Qwen3 系列。该迁移建议具有一致性，非矛盾信息。
|
||||
|
||||
## 关键参数
|
||||
|
||||
- **Prompt 相关**：文生文场景推荐使用结构化 Prompt 框架（背景/目的/风格/语气/受众/输出）；文生图/文生视频需区分 `prompt`（正向）、`negative_prompt`（反向），V2 版本支持 `prompt_extend` 自动改写；Vidu 支持 `大动态`/`固定镜头` 等运镜关键词 [Vidu视频生成Prompt指南](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/vidu-video-generation-prompt-guide.md)。
|
||||
- **流式与思考模式**：多数第三方模型（DeepSeek、Kimi、GLM、MiniMax、MiMo、Stepfun）通过 `extra_body={"enable_thinking": true}` 或 `reasoning_effort` 控制思考过程输出，`reasoning_content` 字段承载推理链，`content` 字段承载最终答案。
|
||||
- **缓存与限流**：显式缓存通过 `cache_control` 标记实现确定性命中，适用于 Agent 长上下文管理；限流维度包括 RPM/TPM（分钟级）、RPS/TPS（瞬时）、Traffic Burst（增速），需配合 `X-DashScope-Wait-Timeout` 请求头应对突发流量 [限流应对最佳实践](../../raw/model-user-guide/use-cases/rate-limiting-best-practices.md)。
|
||||
不同模型与任务类型对应关键参数，需按规范设置：
|
||||
|
||||
- **文本生成**：`model`（模型标识符）、`messages`（对话历史）、`stream`（流式开关）、`extra_body`（非标准参数，如 `enable_thinking: true` 或 `reasoning_effort: "max"`）。[OpenAI 兼容接口](../concepts/openai-compatible-interface.md)中，`extra_body` 是传递厂商特有参数的标准方式。
|
||||
|
||||
- **文生图/图生图**：`prompt`（正向提示词）、`negative_prompt`（反向提示词）、`prompt_extend`（是否启用智能扩写，默认 `true`）。详见 [文生图Prompt指南](../../raw/model-user-guide/use-cases/text-to-image-prompt.md)。
|
||||
|
||||
- **文生视频/图生视频**：除基础 `prompt` 外，支持 `motion`（运动描述）、`camera`（运镜控制）、`sound`（声音描述）等维度。[文生视频/图生视频Prompt指南](../../raw/model-user-guide/use-cases/text-to-video-prompt.md) 提供了多镜头公式与参考视频公式。
|
||||
|
||||
- **显式缓存**：在请求头中添加 `X-DashScope-Wait-Timeout`（服务端排队等待）或在消息体中使用 `cache_control` 字段（如 Anthropic 协议兼容工具），实现确定性缓存命中。
|
||||
|
||||
- **限流应对**：`X-DashScope-Wait-Timeout`（突发流量排队）、客户端需同步调整超时时间；[Token](../concepts/token.md) Plan/Coding Plan 等套餐对应不同 Base URL，影响限流额度。
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **模型调用**：通过 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)（`base_url` 指向 `compatible-mode/v1`）或 DashScope SDK 调用，需配置 API Key 及业务空间 ID。
|
||||
2. **工作流编排**：利用百炼可视化节点（文本/图像/视频生成节点）构建无限画布创作流，或通过函数计算集成 Wan2.7 与 HappyHorse 实现影视全流程自动化 [HappyHorse 打造一站式影视创作平台](../../raw/model-user-guide/use-cases/infinite-canvas.md)。
|
||||
3. **RAG 构建**：基于 LlamaIndex，使用 `DashScopeParse` 解析 PDF/DOCX，`DashScopeCloudIndex` 创建知识库，`DashScopeCloudRetriever` 检索，支持多源交叉验证与结构化报告生成 [基于LlamaIndex构建RAG应用](../../raw/model-user-guide/use-cases/build-rag-applications-based-on-llamaindex.md)。
|
||||
4. **实时交互**：WebRTC 方式适用于浏览器端低延迟音视频通话（需处理 SDP 代理），AOQ SDK 适用于 Android/iOS/HarmonyOS 原生应用，多模态交互套件支持 AI 眼镜等硬件场景。
|
||||
开发者可通过多种方式集成百炼能力：
|
||||
|
||||
- **API 直接调用**：使用 [OpenAI 兼容接口](../concepts/openai-compatible-interface.md)（推荐）或 DashScope 原生 SDK。所有第三方模型（如 Kimi、GLM、MiniMax）均提供 OpenAI 兼容调用示例，要求配置地域专属 `base_url`（如华北2为 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`）并传入 `DASHSCOPE_API_KEY`。
|
||||
|
||||
- **低代码编排**：通过百炼控制台的“无限画布”可视化拖拽节点（文本、图像、视频、特效），构建影视创作、电商设计等端到端工作流。[HappyHorse 打造一站式影视创作平台](../../raw/model-user-guide/use-cases/infinite-canvas.md) 是典型范例。
|
||||
|
||||
- **RAG 应用开发**：基于 LlamaIndex 集成百炼知识库服务，使用 `DashScopeCloudIndex` 创建索引，`DashScopeCloudRetriever` 检索，`DashScopeCloudQueryEngine` 查询。[基于LlamaIndex构建RAG应用](../../raw/model-user-guide/use-cases/build-rag-applications-based-on-llamaindex.md) 提供完整代码示例。
|
||||
|
||||
- **实时交互集成**：WebRTC 方式适用于浏览器端（需处理 SDP 代理），AOQ SDK 适用于移动端（Android/iOS/HarmonyOS）。两者均需业务侧 AppServer 签发 [Token](../concepts/token.md) 并管理会话生命周期。
|
||||
|
||||
- **深度研究与文档转换**：Qwen-Deep-Research 模型自动规划检索路径并生成结构化报告；文档转视频方案则分步执行切片、图文生成、语音合成、视频剪辑。[深度研究：生成你的独家洞察报告](../../raw/model-user-guide/use-cases/deep-research.md) 与 [借助大模型将文档转换为视频](../../raw/model-user-guide/use-cases/use-llm-to-convert-document-to-video.md) 分别详述其流程。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **地域与模型绑定**：第三方模型（DeepSeek、Kimi、GLM、MiniMax、MiMo、Stepfun）普遍仅限华北2（北京）地域开通与调用，跨地域请求将失败。
|
||||
- **[Token](../concepts/token.md) 与费用**：所有 API 调用按 [Token](../concepts/token.md) 计费，免费额度耗尽后需关注实际成本（如深度研究方案约 6 元/次，AI 教学辅学约 1 元/次）。显式缓存首次写入产生 25% 额外开销，但后续命中可节省 90% 成本。
|
||||
- **技术约束**：WebRTC 模式下浏览器无法直连服务端 SDP 交换，需业务 AppServer 代理；Vidu 视频生成对提示词句式敏感，应避免主体物过多/分散及模糊术语；`qwen3.5-omni-plus-realtime` 的 WebRTC 实现仅支持 `server_vad` 模式，不支持手动 VAD。
|
||||
- **兼容性风险**：`enable_thinking` 和 `reasoning_effort` 为非 OpenAI 标准参数，需通过 `extra_body`（Python）或顶层参数（Node.js）传入，不同 SDK 实现方式存在差异。
|
||||
- **地域与域名约束**：绝大多数第三方模型（DeepSeek、Kimi、GLM、MiniMax、MiMo、Stepfun）仅支持华北2（北京）地域，且强烈推荐使用业务空间专属域名 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com` 替代通用域名以获得更高稳定性与性能。
|
||||
|
||||
- **限流策略**：百炼 API 按 RPM（每分钟请求数）、TPM（每分钟 [Token](../concepts/token.md) 数）、RPS/TPS（每秒峰值）、Traffic Burst（增速突增）四维限流。单纯重试无效，需结合 [限流应对最佳实践](../../raw/model-user-guide/use-cases/rate-limiting-best-practices.md) 中的服务端排队、客户端令牌桶或架构层 MQ 削峰。
|
||||
|
||||
- **缓存与成本**：显式缓存对高频复用 Prompt 场景收益显著（首次写入成本为标准价25%，后续命中节省90%），但需确保输入内容稳定；`cache_control` 仅在 Anthropic 协议兼容工具（Claude Code、OpenCode、OpenClaw）中默认启用。
|
||||
|
||||
- **模型生命周期**：第三方模型存在明确下架计划（如 DeepSeek 系列于 2026年10月、Kimi/GLM/MiniMax 于 2026年7月），生产环境应提前规划迁移到 Qwen3 系列。
|
||||
|
||||
- **安全与合规**：训练数据需脱敏处理，避免含 PII 或敏感信息；WebRTC 实现中浏览器受 CORS 限制，SDP 交换必须由业务后端代理，不可前端直连。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [HappyHorse 打造一站式影视创作平台](../../raw/model-user-guide/use-cases/infinite-canvas.md)
|
||||
- [深度研究：生成你的独家洞察报告](../../raw/model-user-guide/use-cases/deep-research.md)
|
||||
- [高效搭建 AI 智能体与工作流应用](../../raw/model-user-guide/use-cases/build-ai-applications-based-on-alibaba-cloud-model-studio.md)
|
||||
- [深度研究：生成你的独家洞察报告](../../raw/model-user-guide/use-cases/deep-research.md)
|
||||
- [AI 解题 + 批改：推动课程教学智变](../../raw/model-user-guide/use-cases/ai-homework-helper.md)
|
||||
- [文生文Prompt指南](../../raw/model-user-guide/use-cases/prompt-engineering-guide.md)
|
||||
- [文生图Prompt指南](../../raw/model-user-guide/use-cases/text-to-image-prompt.md)
|
||||
- [文生视频/图生视频Prompt指南](../../raw/model-user-guide/use-cases/text-to-video-prompt.md)
|
||||
- [自定义模型调优、部署与评测](../../raw/model-user-guide/use-cases/model-training-best-practices.md)
|
||||
- [基于LlamaIndex构建RAG应用](../../raw/model-user-guide/use-cases/build-rag-applications-based-on-llamaindex.md)
|
||||
- [借助大模型将文档转换为视频](../../raw/model-user-guide/use-cases/use-llm-to-convert-document-to-video.md)
|
||||
- [限流应对最佳实践 ](../../raw/model-user-guide/use-cases/rate-limiting-best-practices.md)
|
||||
- [显式缓存最佳实践](../../raw/model-user-guide/use-cases/explicit-cache-guide.md)
|
||||
- [限流应对最佳实践 ](../../raw/model-user-guide/use-cases/rate-limiting-best-practices.md)
|
||||
- [借助大模型将文档转换为视频](../../raw/model-user-guide/use-cases/use-llm-to-convert-document-to-video.md)
|
||||
- [通过WebRTC使用多模态交互套件实现实时通话](../../raw/model-user-guide/use-cases/best-practice-webrtc-multimodal-dialog.md)
|
||||
- [通过WebRTC使用qwen3.5-omni-plus-realtime实现实时通话](../../raw/model-user-guide/use-cases/best-practice-webrtc-omni-realtime.md)
|
||||
- [通过AOQ使用qwen3.5-omni-plus-realtime实现实时通话](../../raw/model-user-guide/use-cases/best-practice-aoq-omni-realtime.md)
|
||||
- [自定义模型调优、部署与评测](../../raw/model-user-guide/use-cases/model-training-best-practices.md)
|
||||
- [通过WebRTC使用多模态交互套件实现实时通话](../../raw/model-user-guide/use-cases/best-practice-webrtc-multimodal-dialog.md)
|
||||
- [DeepSeek-硅基流动](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/siliconflow-deepseek-api.md)
|
||||
- [DeepSeek-阿里云](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/deepseek-api.md)
|
||||
- [DeepSeek](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/deepseek-api-by-vanchin.md)
|
||||
- [Kimi-月之暗面](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/kimi-api-by-moonshot-ai.md)
|
||||
- [Kimi](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/kimi-api.md)
|
||||
- [GLM](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/glm.md)
|
||||
- [GLM-智谱](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/glm-zhipu.md)
|
||||
- [DeepSeek-硅基流动](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/siliconflow-deepseek-api.md)
|
||||
- [MiniMax](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/minimax-api.md)
|
||||
- [MiniMax](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/minimax-api-by-minimax.md)
|
||||
- [Vidu视频生成Prompt指南](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/vidu-video-generation-prompt-guide.md)
|
||||
- [MiMo-小米](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/mimo.md)
|
||||
- [Kimi-月之暗面](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/kimi-api-by-moonshot-ai.md)
|
||||
- [Stepfun-阶跃星辰](../../raw/model-user-guide/use-cases/third-party-model-integration-tutorial/stepfun.md)
|
||||
|
||||
|
||||
|
||||
@@ -1,66 +1,68 @@
|
||||
# use chat client or development tool
|
||||
|
||||
阿里云百炼支持通过多种主流 AI 编程客户端与开发工具接入模型服务，覆盖本地 CLI 工具（如 Hermes Agent、Qwen Code）、桌面 IDE（如 Cursor、Cherry Studio）、VS Code [插件](../concepts/plugin.md)（如 Cline）、开源 Agent 平台（如 OpenClaw、QwenPaw）以及工作流平台（如 Dify）。所有工具均通过 OpenAI 兼容协议或 Anthropic 兼容协议对接，开发者可基于自身技术栈和使用场景选择合适工具。
|
||||
阿里云百炼支持通过多种主流 AI 编程工具、桌面客户端及开发平台接入模型服务。开发者可基于 OpenAI 或 Anthropic 兼容协议，使用 [Token](../concepts/token.md) Plan 个人版/团队版、Coding Plan 或按量计费方案快速集成。所有工具均需正确配置 API Key、Base URL 及模型 ID，且不同计费方案的凭证不互通。
|
||||
|
||||
## 支持的模型/功能
|
||||
|
||||
百炼当前支持的模型因计费方案而异，**[Token](../concepts/token.md) Plan 个人版**与**[Token](../concepts/token.md) Plan 团队版**均支持 `qwen3.8-max-preview`（强制开启思考模式）、`qwen3.7-max`、`qwen3.7-plus`、`qwen3.6-flash`、`glm-5.2`、`deepseek-v4-pro` 等文本生成模型；**Coding Plan** 主要支持 `qwen3.7-plus` 等面向编码优化的模型；**按量计费**方案覆盖最全，包括 Qwen-VL、QVQ、Qwen-Omni、万相（wan2.6-t2i）等多模态与 AIGC 模型。
|
||||
> **注意**：Dify 明确不支持 [Token](../concepts/token.md) Plan 个人版、Token Plan 团队版和 Coding Plan 接入，仅允许使用按量付费 API Key，详见 [Dify](../../raw/model-user-guide/use-chat-client-or-development-tool/dify.md) 文档。
|
||||
视觉与视频生成类模型（如文生图、文生视频）需通过异步 API 调用，不适用于标准聊天客户端，推荐使用 Postman 或 cURL 进行测试验证，具体流程见 [使用Postman或cURL调用图像/视频生成API](../../raw/model-user-guide/use-chat-client-or-development-tool/first-call-to-image-and-video-api.md)。
|
||||
此外，部分工具（如 Cursor 免费版、Codex 旧版本）对模型调用存在限制：Cursor 免费版仅支持 Auto 模式，不支持自定义模型；Codex 对 `glm-5` 等模型需降级至 v0.80.0 并使用 Chat/Completions API，详见 [Codex](../../raw/model-user-guide/use-chat-client-or-development-tool/codex.md)。
|
||||
- **通用文本模型**：qwen3.8-max-preview（强制启用思考模式）、qwen3.7-max、qwen3.7-plus、qwen3.6-flash、glm-5.2、deepseek-v4-pro 等，详见 [Token Plan 个人版支持的模型](https://help.aliyun.com/zh/model-studio/token-plan-personal-overview)。
|
||||
- **视觉与[多模态](../concepts/multi-modal.md)模型**：Qwen-VL、QVQ、Qwen-Omni、Qwen-Audio、Qwen-OCR 等，**仅支持通过 Dify 的 HTTP 节点或百炼原生 API 调用**，不支持直接在 Chatbox、Cursor 等客户端中配置 [Dify](../../raw/model-user-guide/use-chat-client-or-development-tool/dify.md)。
|
||||
- **图像/视频生成模型**：wan2.6-t2i、wan2.5-t2i-preview 等，**必须使用异步调用机制**（创建任务 + 轮询查询），不支持同步 REST 调用 [使用Postman或cURL调用图像/视频生成API](../../raw/model-user-guide/use-chat-client-or-development-tool/first-call-to-image-and-video-api.md)。
|
||||
- **Embedding/Rerank 模型**：text-embedding-v4、gte-rerank-v2 等，仅限在 Dify 知识库等特定场景中配置使用。
|
||||
|
||||
> **注意**：[Token](../concepts/token.md) Plan 个人版、[Token](../concepts/token.md) Plan 团队版和 Coding Plan **不支持工作流/自动化平台（如 Dify、n8n、Coze）及 API 测试工具（如 Postman、cURL）**；违规使用可能导致订阅暂停或 API Key 封禁 [更多工具](../../raw/model-user-guide/use-chat-client-or-development-tool/more-tools.md)。
|
||||
|
||||
## 关键参数
|
||||
|
||||
| 参数 | 说明 | 常见取值示例 |
|
||||
|------|------|-------------|
|
||||
| `base_url` / `baseUrl` / `API 主机` | 模型服务端点地址，**必须与所选计费方案及地域严格匹配** | Token Plan 个人版 OpenAI 协议：<br>`https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`<br>按量计费（北京）：<br>`https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1` |
|
||||
| `api_key` / `API 密钥` | 认证凭证，**不同计费方案的 API Key 不通用** | Token Plan 个人版专属 Key（控制台路径：`/efm/subscription/overview`） |
|
||||
| `model` / `Model ID` | 模型标识符，注意命名规范差异 | `qwen3.8-max-preview`（标准名），但在 Cursor 中 `kimi-k2.6` 需写为 `kimi-k2-6`，`glm-5.2` 需写为 `glm-5-2`，详见 [Cursor](../../raw/model-user-guide/use-chat-client-or-development-tool/cursor.md) |
|
||||
| `api_mode` / `wire_api` | 协议类型标识（仅 Anthropic 协议工具需显式指定） | `anthropic_messages`（Hermes Agent）、`responses`（Codex） |
|
||||
| `enable_thinking` / `thinking` | qwen3.8-max-preview 强制启用参数，不可关闭 | `true`（OpenClaw、Qwen Code 等均需在配置中显式启用） |
|
||||
|
||||
> **注意**：`qwen3.8-max-preview` 的 `temperature` 在思考模式下有硬性下限（0.6），传入值低于该阈值将被自动修正，此行为在 [Hermes Agent](../../raw/model-user-guide/use-chat-client-or-development-tool/hermes-agent.md)、[Claude Code](../../raw/model-user-guide/use-chat-client-or-development-tool/claude-code.md)、[Qwen Code](../../raw/model-user-guide/use-chat-client-or-development-tool/qwen-code.md) 等多份文档中一致确认。
|
||||
| 参数 | 说明 | 示例值 |
|
||||
|------|------|--------|
|
||||
| `API Key` | 方案专属密钥，不可跨方案复用 | Token Plan 个人版：`sk-xxx`（控制台获取） |
|
||||
| `Base URL` | 必须与 API Key 所属方案及地域严格匹配 | OpenAI 兼容：<br>`https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`<br>Anthropic 兼容：<br>`https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic` |
|
||||
| `Model ID` | 模型名称需与方案支持列表一致；部分工具要求别名（如 `kimi-k2.6` → `kimi-k2-6`） | `qwen3.8-max-preview`, `glm-5-2` |
|
||||
| `thinking` / `enable_thinking` | qwen3.8-max-preview 强制启用，不可关闭；temperature < 0.6 时自动设为 0.6 | `true`（必填） |
|
||||
| `reasoning_effort` | 控制推理深度，取值 `xhigh`/`medium`/`low`，默认 `xhigh` | `xhigh` |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. **安装工具**：根据操作系统选择对应安装方式（npm、curl 脚本、GUI 安装包等），多数工具要求 Node.js ≥18（如 [Claude Code](../../raw/model-user-guide/use-chat-client-or-development-tool/claude-code.md)、[Codex](../../raw/model-user-guide/use-chat-client-or-development-tool/codex.md)）或 Python（如 [Hermes Agent](../../raw/model-user-guide/use-chat-client-or-development-tool/hermes-agent.md)）。
|
||||
2. **配置凭证**：
|
||||
- CLI 工具（如 Hermes Agent、Qwen Code）通常提供 `hermes config set` 或 `/auth` 交互式命令；
|
||||
- GUI 工具（如 Cursor、Cherry Studio）通过设置界面填写 API Key、Base URL 和 Model ID；
|
||||
- [插件](../concepts/plugin.md)（如 Cline）在 VS Code 扩展设置中选择 “Bring my own API key” 并填入参数；
|
||||
- 开源平台（如 QwenPaw）通过 Web Console 的「设置 > 模型」完成配置。
|
||||
3. **验证连接**：发送简单请求（如“你好”）并检查响应；若报错，优先排查 API Key 与 Base URL 是否来自同一计费方案及地域（如 [Cline](../../raw/model-user-guide/use-chat-client-or-development-tool/cline.md) 报错 401 的常见原因）。
|
||||
4. **高级功能**：启用思考模式（R1 messages format）、配置 `reasoning_effort`（xhigh/medium/low）、调整 `max_tokens` 等需查阅各工具专属文档的进阶配置节。
|
||||
1. **安装工具**：根据文档要求安装对应 CLI 或 GUI 工具（如 `npm install -g opencode-ai`、下载 Cursor 安装包等）。
|
||||
2. **配置凭证**：
|
||||
- 多数工具提供交互式 `/auth` 或图形化设置界面（如 Qwen Code、Qoder、Cherry Studio）；
|
||||
- 部分工具需手动编辑配置文件（如 `~/.hermes/config.yaml`、`~/.qwen/settings.json`）；
|
||||
- 环境变量方式（如 Codex 的 `OPENAI_API_KEY`）需 `source` 生效。
|
||||
3. **验证连接**：发送简单请求（如“你好”）或运行 `--version` 命令确认环境就绪。
|
||||
4. **高级能力**：
|
||||
- 启用思考模式需显式设置 `enable_thinking: true` 或勾选对应开关；
|
||||
- 使用百炼 CLI 技能需先全局安装 `npm install -g bailian-cli`，再在工具中配置 API Key [Qoder](../../raw/model-user-guide/use-chat-client-or-development-tool/qoder-agent.md)。
|
||||
|
||||
## 限制和注意事项
|
||||
|
||||
- **计费方案适用范围严格隔离**：Token Plan 个人版/团队版/Coding Plan 仅限 AI 编程工具（CLI、IDE、Agent）使用；工作流平台（Dify、n8n）、API 测试工具（Postman）、自定义后端应用等**明确禁止接入**，违规可能导致订阅暂停或 API Key 封禁，详见 [更多工具](../../raw/model-user-guide/use-chat-client-or-development-tool/more-tools.md)。
|
||||
- **地域绑定强制**：按量计费的 API Key 与 `base_url` 中的 `WorkspaceId` 及地域必须一致；Token Plan 与 Coding Plan 的 Base URL 为固定域名，不支持跨地域调用。免费额度仅适用于华北2（北京）地域，其他地域调用将直接计费（[Cherry Studio](../../raw/model-user-guide/use-chat-client-or-development-tool/cherry-studio.md)）。
|
||||
- **模型兼容性差异**：
|
||||
- OpenAI 协议工具（Cursor、Cherry Studio、QwenPaw）普遍使用 `/compatible-mode/v1`；
|
||||
- Anthropic 协议工具（Hermes Agent、Claude Code、OpenClaw）使用 `/apps/anthropic`；
|
||||
- Codex 对部分模型需降级并切换 `wire_api` 为 `chat`（[Codex](../../raw/model-user-guide/use-chat-client-or-development-tool/codex.md)）；
|
||||
- Qwen3.8-max-preview 的思考模式参数（`enable_thinking`）在 OpenClaw、Qwen Code、Kilo CLI 等配置中均为必需字段，缺失将导致调用失败。
|
||||
- **错误排查优先级**：遇到 401（Unauthorized）先核对 API Key 与 Base URL 方案一致性；遇到 400（InvalidParameter）检查是否遗漏 `Enable R1 messages format`（Cline）或 `reasoning_effort` 格式错误；遇到模型不可用，确认所选模型是否在当前套餐支持列表内（如 [Qoder CN](../../raw/model-user-guide/use-chat-client-or-development-tool/lingma-agent.md) 报错“自定义模型服务异常”常因模型不支持）。
|
||||
- **地域绑定**：按量计费的 `WorkspaceId` 和 API Key 必须同地域；免费额度仅限华北2（北京）地域 [Cherry Studio](../../raw/model-user-guide/use-chat-client-or-development-tool/cherry-studio.md)。
|
||||
- **模型兼容性**：
|
||||
- qwen3.8-max-preview 仅支持 Anthropic 协议下的 `thinking` 模式，OpenAI 协议下需额外配置 `extra_body.enable_thinking=true`；
|
||||
- 部分旧版工具（如 Codex v0.80.0）对非 Responses API 模型（如 glm-5）需降级使用。
|
||||
- **权限校验**：RAM 子账号需在业务空间中显式授予模型调用权限 [Cherry Studio](../../raw/model-user-guide/use-chat-client-or-development-tool/cherry-studio.md)。
|
||||
- **错误排查**：
|
||||
- `401 Incorrect API key provided`：检查 Key/URL 是否同方案、同地域；
|
||||
- `400 InternalError.Algo.InvalidParameter`：Qwen3/QwQ 模型需启用 R1 messages format（Cline 设置中勾选）；
|
||||
- “Named models unavailable”：Cursor 免费版仅支持 Auto 模式，需升级至 Pro 版本 [Cursor](../../raw/model-user-guide/use-chat-client-or-development-tool/cursor.md)。
|
||||
|
||||
## 来源文档
|
||||
|
||||
- [OpenClaw](../../raw/model-user-guide/use-chat-client-or-development-tool/openclaw.md)
|
||||
- [Hermes Agent](../../raw/model-user-guide/use-chat-client-or-development-tool/hermes-agent.md)
|
||||
- [Claude Code](../../raw/model-user-guide/use-chat-client-or-development-tool/claude-code.md)
|
||||
- [Cursor](../../raw/model-user-guide/use-chat-client-or-development-tool/cursor.md)
|
||||
- [Qwen Code](../../raw/model-user-guide/use-chat-client-or-development-tool/qwen-code.md)
|
||||
- [Codex](../../raw/model-user-guide/use-chat-client-or-development-tool/codex.md)
|
||||
- [OpenCode](../../raw/model-user-guide/use-chat-client-or-development-tool/opencode.md)
|
||||
- [Chatbox](../../raw/model-user-guide/use-chat-client-or-development-tool/chatbox.md)
|
||||
- [Cursor](../../raw/model-user-guide/use-chat-client-or-development-tool/cursor.md)
|
||||
- [Codex](../../raw/model-user-guide/use-chat-client-or-development-tool/codex.md)
|
||||
- [Qwen Code](../../raw/model-user-guide/use-chat-client-or-development-tool/qwen-code.md)
|
||||
- [QwenPaw](../../raw/model-user-guide/use-chat-client-or-development-tool/qwenpaw.md)
|
||||
- [Cherry Studio](../../raw/model-user-guide/use-chat-client-or-development-tool/cherry-studio.md)
|
||||
- [Qoder](../../raw/model-user-guide/use-chat-client-or-development-tool/qoder-agent.md)
|
||||
- [Cline](../../raw/model-user-guide/use-chat-client-or-development-tool/cline.md)
|
||||
- [Qoder CN（原 Lingma）](../../raw/model-user-guide/use-chat-client-or-development-tool/lingma-agent.md)
|
||||
- [Chatbox](../../raw/model-user-guide/use-chat-client-or-development-tool/chatbox.md)
|
||||
- [Kilo CLI](../../raw/model-user-guide/use-chat-client-or-development-tool/kilo-cli.md)
|
||||
- [使用Postman或cURL调用图像/视频生成API](../../raw/model-user-guide/use-chat-client-or-development-tool/first-call-to-image-and-video-api.md)
|
||||
- [Dify](../../raw/model-user-guide/use-chat-client-or-development-tool/dify.md)
|
||||
- [QwenPaw](../../raw/model-user-guide/use-chat-client-or-development-tool/qwenpaw.md)
|
||||
- [更多工具](../../raw/model-user-guide/use-chat-client-or-development-tool/more-tools.md)
|
||||
- [Qoder CN（原 Lingma）](../../raw/model-user-guide/use-chat-client-or-development-tool/lingma-agent.md)
|
||||
- [Qoder](../../raw/model-user-guide/use-chat-client-or-development-tool/qoder-agent.md)
|
||||
|
||||
|
||||
|
||||
@@ -41,7 +41,7 @@
|
||||
|
||||
- [3d generation](api/3d-generation.md) — 1 篇源文档
|
||||
- [application call](api/application-call.md) — 5 篇源文档
|
||||
- [application component api reference](api/application-component-api-reference.md) — 58 篇源文档
|
||||
- [application component api reference](api/application-component-api-reference.md) — 57 篇源文档
|
||||
- [file management api](api/file-management-api.md) — 1 篇源文档
|
||||
- [frameworks](api/frameworks.md) — 3 篇源文档
|
||||
- [image generation](api/image-generation.md) — 27 篇源文档
|
||||
@@ -56,7 +56,7 @@
|
||||
- [preparations](api/preparations.md) — 4 篇源文档
|
||||
- [qwen api reference](api/qwen-api-reference.md) — 1 篇源文档
|
||||
- [realtime api user guide](api/realtime-api-user-guide.md) — 12 篇源文档
|
||||
- [toolkits and frameworks](api/toolkits-and-frameworks.md) — 10 篇源文档
|
||||
- [toolkits and frameworks](api/toolkits-and-frameworks.md) — 9 篇源文档
|
||||
- [vector and sort](api/vector-and-sort.md) — 4 篇源文档
|
||||
- [video generation api](api/video-generation-api.md) — 34 篇源文档
|
||||
|
||||
@@ -64,20 +64,20 @@
|
||||
|
||||
- [OpenAI 兼容接口](concepts/openai-compatible-interface.md) — 关联 5 个主题
|
||||
- [Prompt 工程](concepts/prompt-engineering.md) — 关联 4 个主题
|
||||
- [Token](concepts/token.md) — 关联 4 个主题
|
||||
- [函数调用](concepts/function-calling.md) — 关联 3 个主题
|
||||
- [异步任务](concepts/asynchronous-task.md) — 关联 5 个主题
|
||||
- [插件](concepts/plugin.md) — 关联 4 个主题
|
||||
- [检索增强生成](concepts/rag.md) — 关联 5 个主题
|
||||
- [模型上下文协议](concepts/mcp.md) — 关联 3 个主题
|
||||
- [Token](concepts/token.md) — 关联 5 个主题
|
||||
- [函数调用](concepts/function-calling.md) — 关联 4 个主题
|
||||
- [多模态](concepts/multi-modal.md) — 关联 6 个主题
|
||||
- [文件处理](concepts/file-processing.md) — 关联 5 个主题
|
||||
- [检索增强生成](concepts/rag.md) — 关联 6 个主题
|
||||
- [模型上下文协议](concepts/mcp.md) — 关联 5 个主题
|
||||
- [流式输出](concepts/streaming-output.md) — 关联 5 个主题
|
||||
- [长期记忆](concepts/long-term-memory.md) — 关联 3 个主题
|
||||
- [长期记忆](concepts/long-term-memory.md) — 关联 4 个主题
|
||||
|
||||
## 对比分析
|
||||
|
||||
- [多模态生成能力对比：Image Generation vs Video Generation API vs 3D Generation](comparisons/generation-apis.md) — 对比 3 个主题
|
||||
- [实时 API 方案对比：Realtime API vs Omni Realtime API](comparisons/realtime-api-comparison.md) — 对比 2 个主题
|
||||
- [应用编排与调用方案对比：Managed Agents vs Application Call vs Bailian Application Calling](comparisons/application-orchestration.md) — 对比 3 个主题
|
||||
- [模型部署方式对比：Model Production vs Model Deployment 1](comparisons/model-deployment-options.md) — 对比 2 个主题
|
||||
- [知识能力方案对比：Knowledge API vs Knowledge Base](comparisons/knowledge-solutions.md) — 对比 2 个主题
|
||||
- [多模态生成能力对比：图像生成、视频生成与3D生成](comparisons/generation-apis-comparison.md) — 对比 3 个主题
|
||||
- [实时 API 方案对比：Omni Realtime API vs Realtime API](comparisons/realtime-api-comparison.md) — 对比 2 个主题
|
||||
- [应用构建框架对比：Managed Agents、Application Component API 与 Toolkits and Frameworks](comparisons/application-frameworks-comparison.md) — 对比 3 个主题
|
||||
- [模型部署方式对比：Model Deployment、Model Production 与 Fine-tuning](comparisons/model-deployment-options.md) — 对比 3 个主题
|
||||
- [长期记忆方案对比：Long Term Memory 与 Memory Library](comparisons/memory-solutions-comparison.md) — 对比 2 个主题
|
||||
|
||||
|
||||
Reference in New Issue
Block a user