发起第一次文本生成调用
文本生成模型接收自然语言输入,生成问答、写作、摘要、翻译、结构化输出等文本内容。
文本生成请求通常以
模型会以
开始之前,请先获取 API Key、将其设为环境变量,并按需安装 OpenAI 或 DashScope SDK。
根据你的技术栈选择合适的 API 风格:
同步调用跑通后,可通过异步调用提升高并发场景下的吞吐量。
响应
将原始数据直接输入大语言模型会因上下文长度限制导致成本上升、质量下降。上下文工程通过动态加载精准知识来提升输出质量和效率。核心技术包括:
适用于复杂场景:
完整的模型调用参数列表,请参见 OpenAI Compatible API 参考和 DashScope API 参考。
为什么输入 Token 数比我发送的文本 Token 数多?
在处理对话时,系统会使用对话模板(Chat Template)对输入的原始文本进行包装,添加角色标识、消息边界等控制标记。这些由系统添加的标记同样会计入 Token。
例如,向
请求结构
文本生成请求通常以 messages 数组的形式发送,每条消息包含 role(角色)和 content(内容)两个字段。
- System message:设定模型行为的全局指令。
- User message:用户的输入或任务描述。
- Assistant message:模型的回复内容。
user 消息,可选地附带一条 system 消息以获得更稳定、可控的输出。
system 消息非必需,但如果你希望模型表现更一致,建议添加。assistant 消息返回回复。
发起第一次调用
开始之前,请先获取 API Key、将其设为环境变量,并按需安装 OpenAI 或 DashScope SDK。
根据你的技术栈选择合适的 API 风格:
- 新项目建议使用 OpenAI Compatible -- Responses API。
- 已有 OpenAI 兼容代码需要迁移时,使用 OpenAI Compatible -- Chat Completions API。
- 偏好原生 SDK 时,使用 DashScope。
- OpenAI Compatible -- Responses API
- OpenAI Compatible -- Chat Completions API
- DashScope
- DashScope -- 多模态接口
接口说明、代码示例和迁移指南请参见 OpenAI compatible - Responses。响应响应包含以下主要字段:以下为 qwen3.8-max 的历史响应示例。
-
id:响应 ID。 -
output:输出列表,包含reasoning(思考过程)和message(回复内容)。reasoning字段仅在开启深度思考时出现(例如 Qwen3.5 和 Qwen3.6 系列默认开启)。 -
usage:Token 用量统计。
完整 JSON 响应
完整 JSON 响应
异步调用
同步调用跑通后,可通过异步调用提升高并发场景下的吞吐量。
- OpenAI Compatible -- Chat Completions API
- DashScope
由于调用是异步的,响应顺序可能与示例不同。
生产优化
构建更优质的上下文
将原始数据直接输入大语言模型会因上下文长度限制导致成本上升、质量下降。上下文工程通过动态加载精准知识来提升输出质量和效率。核心技术包括:
- Prompt 工程:设计和优化提示词,引导模型生成预期的输出。详见文本生成 Prompt 指南。
- 检索增强生成(RAG):当模型需要基于产品文档、技术手册等外部知识库回答问题时使用。
- 工具调用:让模型获取天气、交通等实时数据,或执行调用 API、发送邮件等操作。
- 记忆机制:为模型提供短期和长期记忆,使其理解对话历史。
控制回复多样性
temperature 和 top_p 用于控制生成文本的多样性。数值越高,内容越多样;数值越低,内容越确定。为准确评估参数效果,建议每次只调整一个。
- temperature:范围 [0, 2)。侧重调整随机性。
- top_p:范围 (0, 1]。通过概率阈值筛选回复。
- 高多样性(示例
temperature=0.9):适用于需要创意、想象力和新颖表达的场景,如创意写作、头脑风暴或市场营销文案。
- 高确定性(示例
temperature=0.1):适用于要求内容准确、严谨和可预测的场景,如事实问答、代码生成或法律文本。
原理介绍
原理介绍
temperature:
- temperature 越高,Token 概率分布越平坦(高概率 Token 的概率降低,低概率 Token 的概率上升),模型选择下一个 Token 时更随机。
- temperature 越低,Token 概率分布越陡峭(高概率 Token 被选取的概率更高,低概率 Token 的概率更低),模型更倾向于选择高概率的少数 Token。
- top_p 越高,考虑的 Token 越多,生成的文本更多样。
- top_p 越低,考虑的 Token 越少,生成的文本更集中和确定。
探索更多文本生成功能
适用于复杂场景:
- 多轮对话:适用于追问、信息采集等需要连续对话的场景。
- 流式输出:适用于聊天机器人或实时代码生成,提升用户体验并避免长响应导致的超时。
- 深度思考:适用于复杂推理或政策分析等需要高质量结构化回答的场景。
- 结构化输出:当需要模型以稳定的 JSON 格式回复,用于程序化处理或数据解析时使用。
- 续写模式:适用于代码补全或长文写作,让模型从现有文本继续生成。
参考
完整的模型调用参数列表,请参见 OpenAI Compatible API 参考和 DashScope API 参考。
常见问题
为什么输入 Token 数比我发送的文本 Token 数多?
在处理对话时,系统会使用对话模板(Chat Template)对输入的原始文本进行包装,添加角色标识、消息边界等控制标记。这些由系统添加的标记同样会计入 Token。
例如,向 qwen3.8-max 发送消息 {"role": "user", "content": "你好"},"你好"在分词(Tokenize)后仅对应 1 个 Token,但系统处理时,实际输入完整文本为 <|im_start|>user\n你好<|im_end|>\n<|im_start|>assistant\n<think>,分词后总 Token 数会增加到 11 个。
为什么 Qwen API 无法解析网页链接?
Qwen API 无法直接访问或解析网页链接。你可以使用工具调用,或结合 Python Beautiful Soup 等网页抓取工具来读取网页内容。
为什么通义千问 Web 端和 API 的回复不同?
通义千问 Web 端在 Qwen API 基础上做了额外的工程优化,支持网页解析、联网搜索、绘图、PPT 生成等功能。这些能力不属于大语言模型 API 本身,你可以通过工具调用来实现类似效果。
如何处理模型超时?
使用流式输出可避免超时。流式输出在生成过程中逐步返回 Token,无需等待完整响应。
非流式调用的最大超时时间不少于 300 秒,实际时长因模型而异。若超时仍未完成,服务会中断请求并返回已生成的内容,不再报超时错误。此时响应头包含 x-dashscope-partialresponse: true,表示返回的是超时前的部分结果。若无法获取响应头(例如通过 SDK 调用),可通过 finish_reason 字段辅助判断:值为 null 表示生成内容不完整(但不一定是触发了超时)。
模型可以基于不完整的内容继续生成,详见续写未完成的输出。Java SDK 暂不支持续写模式。
模型能直接生成 Word、Excel、PDF 或 PPT 文件吗?
不能。千问AI平台文本生成模型仅输出纯文本,你可以通过代码或第三方库将文本转换为所需格式。