概述
腾讯混元大模型(Tencent HY)是由腾讯研发的大语言模型,具备强大的中文创作能力,复杂语境下的逻辑推理能力,以及可靠的任务执行能力。
前提条件
已 注册腾讯云 账号并开通 TokenHub 服务。
已在 TokenHub 控制台 获取 API Key。
支持的模型
model(调用参数) | 能力说明 | 上下文窗口 | 最大输入 | 最大输出 |
hy3-preview | 混元 Hy3 Preview 面向 Agent 工作负载设计,采用 MoE 架构,支持交错式思考、结构化输出、Function Calling、Cache 缓存。 | 256k | 192k | 128k |
hy-mt2-pro | 混元翻译旗舰模型,参数量30B-A3B,适合专业领域等对译文质量要求高的场景,有优秀的指令遵循能力。支持语种齐全,重点支持33个语种互译,支持5种民汉/方言。 | 8k | 4k | 4k |
hunyuan-role-latest | 角色扮演模型,适用于 AI 数字分身、AI 角色扮演、AI 情感陪聊等场景。 | 32k | 28k | 4k |
Hy3 preview 调用示例
hy3-preview 兼容 OpenAI Chat Completions API 、OpenAI Responses 、Anthropic Messages API 协议。通用接口规范与所有语言模型一致,请参见 语言模型调用概览 与 API 使用说明。以下为 OpenAI Chat Completions API 调用示例。
说明:
所有示例统一使用
Authorization: Bearer YOUR_API_KEY 鉴权,请将 YOUR_API_KEY 替换为您在 TokenHub 控制台 创建的 API Key。Python / Node.js 直接使用 OpenAI 官方 SDK;Java / Go 使用标准 HTTP 客户端调用 OpenAI 兼容接口。
基础对话
最简单的单轮对话请求,演示基本的请求和响应结构。
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy3-preview","messages": [{"role": "user", "content": "你好,请简单介绍一下你自己。"}],"stream": false,"temperature": 0.9}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)response = client.chat.completions.create(model="hy3-preview",messages=[{"role": "user", "content": "你好,请简单介绍一下你自己。"},],temperature=0.9,)print(response.choices[0].message.content)
import okhttp3.*;import com.google.gson.Gson;import java.util.*;public class BasicChat {public static void main(String[] args) throws Exception {Map<String, Object> body = new HashMap<>();body.put("model", "hy3-preview");body.put("messages", List.of(Map.of("role", "user", "content", "你好,请简单介绍一下你自己。")));body.put("temperature", 0.9);Request request = new Request.Builder().url("https://tokenhub.tencentmaas.com/v1/chat/completions").header("Authorization", "Bearer YOUR_API_KEY").post(RequestBody.create(new Gson().toJson(body),MediaType.parse("application/json"))).build();try (Response response = new OkHttpClient().newCall(request).execute()) {System.out.println(response.body().string());}}}
import OpenAI from 'openai';const client = new OpenAI({apiKey: 'YOUR_API_KEY',baseURL: 'https://tokenhub.tencentmaas.com/v1',});const response = await client.chat.completions.create({model: 'hy3-preview',messages: [{ role: 'user', content: '你好,请简单介绍一下你自己。' },],temperature: 0.9,});console.log(response.choices[0].message.content);
package mainimport ("bytes""encoding/json""fmt""io""net/http")func main() {body, _ := json.Marshal(map[string]interface{}{"model": "hy3-preview","messages": []map[string]string{{"role": "user", "content": "你好,请简单介绍一下你自己。"},},"temperature": 0.9,})req, _ := http.NewRequest("POST","https://tokenhub.tencentmaas.com/v1/chat/completions",bytes.NewBuffer(body))req.Header.Set("Authorization", "Bearer YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")resp, _ := http.DefaultClient.Do(req)defer resp.Body.Close()data, _ := io.ReadAll(resp.Body)fmt.Println(string(data))}
响应示例:
{"id": "REPLACED_ID","object": "chat.completion","model": "hy3-preview","created": 1775146513,"choices": [{"index": 0,"message": {"role": "assistant","content": "你好!我是混元,是由腾讯开发的大模型。我的主要功能是基础信息处理与逻辑响应,比如回答各种问题、解决问题、学习新知识、创造内容,还能陪你闲聊呢。如果你有任何问题都可以随时问我哦。"},"finish_reason": "stop"}],"usage": {"prompt_tokens": 22,"completion_tokens": 50,"total_tokens": 72,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens_details": {"reasoning_tokens": 0}}}
流式请求
设置
stream: true 即可启用流式输出,响应以 SSE(Server-Sent Events)格式按 token 增量返回。如需在最后一个 chunk 拿到完整 usage 统计,请加 stream_options: { "include_usage": true }。curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy3-preview","messages": [{"role": "user", "content": "你好"}],"stream": true,"stream_options": {"include_usage": true}}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)stream = client.chat.completions.create(model="hy3-preview",messages=[{"role": "user", "content": "你好"}],stream=True,stream_options={"include_usage": True},)for chunk in stream:if chunk.choices and chunk.choices[0].delta.content:print(chunk.choices[0].delta.content, end="", flush=True)if chunk.usage:print("\\nusage:", chunk.usage)
import okhttp3.*;import okhttp3.sse.*;import com.google.gson.Gson;import java.util.*;public class StreamingChat {public static void main(String[] args) {Map<String, Object> body = new HashMap<>();body.put("model", "hy3-preview");body.put("messages", List.of(Map.of("role", "user", "content", "你好")));body.put("stream", true);body.put("stream_options", Map.of("include_usage", true));Request request = new Request.Builder().url("https://tokenhub.tencentmaas.com/v1/chat/completions").header("Authorization", "Bearer YOUR_API_KEY").post(RequestBody.create(new Gson().toJson(body),MediaType.parse("application/json"))).build();EventSources.createFactory(new OkHttpClient()).newEventSource(request,new EventSourceListener() {@Override public void onEvent(EventSource es, String id, String type, String data) {if (!"[DONE]".equals(data)) System.out.println(data);}});}}
import OpenAI from 'openai';const client = new OpenAI({apiKey: 'YOUR_API_KEY',baseURL: 'https://tokenhub.tencentmaas.com/v1',});const stream = await client.chat.completions.create({model: 'hy3-preview',messages: [{ role: 'user', content: '你好' }],stream: true,stream_options: { include_usage: true },});for await (const chunk of stream) {process.stdout.write(chunk.choices[0]?.delta?.content || '');if (chunk.usage) console.log('\\nusage:', chunk.usage);}
package mainimport ("bufio""bytes""encoding/json""fmt""net/http""strings")func main() {body, _ := json.Marshal(map[string]interface{}{"model": "hy3-preview","messages": []map[string]string{{"role": "user", "content": "你好"},},"stream": true,"stream_options": map[string]bool{"include_usage": true},})req, _ := http.NewRequest("POST","https://tokenhub.tencentmaas.com/v1/chat/completions",bytes.NewBuffer(body))req.Header.Set("Authorization", "Bearer YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")resp, _ := http.DefaultClient.Do(req)defer resp.Body.Close()scanner := bufio.NewScanner(resp.Body)for scanner.Scan() {line := scanner.Text()if strings.HasPrefix(line, "data: ") && line != "data: [DONE]" {fmt.Println(strings.TrimPrefix(line, "data: "))}}}
响应示例(SSE 片段):
data: {"id": "REPLACED_ID", "object": "chat.completion.chunk", "created": 1779958293, "model": "hy3-preview", "choices": [{"index": 0, "delta": {"role": "assistant"}}]}data: {"id": "REPLACED_ID", "object": "chat.completion.chunk", "created": 1779958293, "model": "hy3-preview", "choices": [{"index": 0, "delta": {"content": "你好"}}]}data: {"id": "REPLACED_ID", "object": "chat.completion.chunk", "created": 1779958293, "model": "hy3-preview", "choices": [{"index": 0, "delta": {"content": "帮你的吗"}}]}data: {"id": "REPLACED_ID", "object": "chat.completion.chunk", "created": 1779958293, "model": "hy3-preview", "choices": [{"index": 0, "delta": {"content": " 😊"}, "finish_reason": "stop"}]}data: {"id": "REPLACED_ID", "object": "chat.completion.chunk", "created": 1779958293, "model": "hy3-preview", "choices": [], "usage": {"prompt_tokens": 16, "completion_tokens": 11, "total_tokens": 27, "prompt_tokens_details": {"cached_tokens": 0}, "completion_tokens_details": {"reasoning_tokens": 0}}}data: [DONE]
深度思考
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy3-preview","messages": [{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"}],"thinking": {"type": "enabled"},"stream": false}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)response = client.chat.completions.create(model="hy3-preview",messages=[{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"},],extra_body={"thinking": {"type": "enabled"}},)# OpenAI SDK 不直接声明 reasoning_content 字段,需用 getattr 访问msg = response.choices[0].messageif hasattr(msg, "reasoning_content"):print("思考过程:", getattr(msg, "reasoning_content"))print("最终回答:", msg.content)
import OpenAI from 'openai';const client = new OpenAI({apiKey: 'YOUR_API_KEY',baseURL: 'https://tokenhub.tencentmaas.com/v1',});// Node.js SDK:thinking 字段直接展开到顶层const response = await client.chat.completions.create({model: 'hy3-preview',messages: [{ role: 'user', content: '小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?' },],thinking: { type: 'enabled' },});const msg = response.choices[0].message;if (msg.reasoning_content) console.log('思考过程:', msg.reasoning_content);console.log('最终回答:', msg.content);
import okhttp3.*;import com.google.gson.Gson;import java.util.*;public class ThinkingChat {public static void main(String[] args) throws Exception {Map<String, Object> body = new HashMap<>();body.put("model", "hy3-preview");body.put("messages", List.of(Map.of("role", "user", "content", "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?")));body.put("thinking", Map.of("type", "enabled"));Request request = new Request.Builder().url("https://tokenhub.tencentmaas.com/v1/chat/completions").header("Authorization", "Bearer YOUR_API_KEY").post(RequestBody.create(new Gson().toJson(body), MediaType.parse("application/json"))).build();try (Response response = new OkHttpClient().newCall(request).execute()) {// 响应体中 message.reasoning_content 为思考过程,message.content 为最终回答System.out.println(response.body().string());}}}
package mainimport ("bytes""encoding/json""fmt""io""net/http")func main() {body, _ := json.Marshal(map[string]interface{}{"model": "hy3-preview","messages": []map[string]string{{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"},},"thinking": map[string]string{"type": "enabled"},})req, _ := http.NewRequest("POST","https://tokenhub.tencentmaas.com/v1/chat/completions",bytes.NewBuffer(body))req.Header.Set("Authorization", "Bearer YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")resp, _ := http.DefaultClient.Do(req)defer resp.Body.Close()data, _ := io.ReadAll(resp.Body)// 响应体中 message.reasoning_content 为思考过程,message.content 为最终回答fmt.Println(string(data))}
响应示例:
启用思考后,响应中会附带
reasoning_content 思考过程字段。{"id": "REPLACED_ID","object": "chat.completion","created": 1775146546,"model": "hy3-preview","choices": [{"index": 0,"message": {"role": "assistant","content": "小明最初有5个苹果,给了小红2个后剩下3个,又买了3个,所以最后剩下 **6个** 苹果。","reasoning_content": "我们被问到:\\"小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?\\" 这是一个简单的算术问题。让我们一步步来:\\n\\n1. 小明一开始有5个苹果。\\n2. 他给了小红2个,所以剩下:5 - 2 = 3个苹果。\\n3. 然后他又买了3个苹果,所以现在有:3 + 3 = 6个苹果。\\n\\n所以最后还剩6个苹果。\\n\\n答案:6。"},"finish_reason": "stop"}],"usage": {"prompt_tokens": 31,"completion_tokens": 132,"total_tokens": 163}}
推理深度配置
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy3-preview","messages": [{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"}],"stream": false,"temperature": 0.9,"reasoning_effort": "high"}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)response = client.chat.completions.create(model="hy3-preview",messages=[{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"},],temperature=0.9,extra_body={"reasoning_effort": "high"},)msg = response.choices[0].messageif hasattr(msg, "reasoning_content"):print("思考过程:", getattr(msg, "reasoning_content"))print("最终回答:", msg.content)
import OpenAI from 'openai';const client = new OpenAI({apiKey: 'YOUR_API_KEY',baseURL: 'https://tokenhub.tencentmaas.com/v1',});const response = await client.chat.completions.create({model: 'hy3-preview',messages: [{ role: 'user', content: '小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?' },],temperature: 0.9,reasoning_effort: 'high',});const msg = response.choices[0].message;if (msg.reasoning_content) console.log('思考过程:', msg.reasoning_content);console.log('最终回答:', msg.content);
import okhttp3.*;import com.google.gson.Gson;import java.util.*;public class ReasoningEffortChat {public static void main(String[] args) throws Exception {Map<String, Object> body = new HashMap<>();body.put("model", "hy3-preview");body.put("messages", List.of(Map.of("role", "user", "content", "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?")));body.put("temperature", 0.9);body.put("reasoning_effort", "high");Request request = new Request.Builder().url("https://tokenhub.tencentmaas.com/v1/chat/completions").header("Authorization", "Bearer YOUR_API_KEY").post(RequestBody.create(new Gson().toJson(body), MediaType.parse("application/json"))).build();try (Response response = new OkHttpClient().newCall(request).execute()) {System.out.println(response.body().string());}}}
package mainimport ("bytes""encoding/json""fmt""io""net/http")func main() {body, _ := json.Marshal(map[string]interface{}{"model": "hy3-preview","messages": []map[string]string{{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"},},"temperature": 0.9,"reasoning_effort": "high",})req, _ := http.NewRequest("POST","https://tokenhub.tencentmaas.com/v1/chat/completions",bytes.NewBuffer(body))req.Header.Set("Authorization", "Bearer YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")resp, _ := http.DefaultClient.Do(req)defer resp.Body.Close()data, _ := io.ReadAll(resp.Body)fmt.Println(string(data))}
响应示例:
启用思考后,响应中会附带
reasoning_content 思考过程字段。{"id": "c95dc87ecce440678c3bb08f5868fee6","object": "chat.completion","created": 1775146546,"model": "hy3-preview","choices": [{"index": 0,"message": {"role": "assistant","content": "小明原本有5个苹果,给了小红2个后剩下: \\n5 - 2 = 3(个) \\n然后又买了3个,现在共有: \\n3 + 3 = 6(个) \\n\\n所以最后还剩 **6个** 苹果。","reasoning_content": "我们被问到:\\"小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?\\" 我们需要逐步计算。\\n\\n初始:5个苹果。\\n给了小红2个:5 - 2 = 3个苹果。\\n又买了3个:3 + 3 = 6个苹果。\\n所以最后还剩6个苹果。\\n\\n答案:6。"},"finish_reason": "stop"}],"usage": {"prompt_tokens": 3,"completion_tokens": 136,"total_tokens": 167}}
交错式思考(深度思考 + 工具调用)
本示例仅用于说明完整流程与字段回传逻辑;实际使用时,请根据业务部署环境和业务字段调整具体值(此案例仅用于理解流程,不代表模型能力边界)。详细说明请参见 交错式思考模式(Interleaved Thinking)。
第 1 轮 - 用户提问:
请求:
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy3-preview","messages": [{ "role": "system", "content": "你是一个 Agent,必须按步骤推理并调用工具完成任务。" },{ "role": "user", "content": "深圳今天天气怎么样?" }],"stream": false,"tool_choice": "auto","reasoning_effort": "high","tools": [{"type": "function","function": {"name": "get_weather","description": "获取某地天气信息,输入 location。","parameters": {"type": "object","properties": { "location": { "type": "string" } },"required": ["location"]}}}]}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)tools = [{"type": "function","function": {"name": "get_weather","description": "获取某地天气信息,输入 location。","parameters": {"type": "object","properties": {"location": {"type": "string"}},"required": ["location"],},},}]messages = [{"role": "system", "content": "你是一个 Agent,必须按步骤推理并调用工具完成任务。"},{"role": "user", "content": "深圳今天天气怎么样?"},]# OpenAI Python SDK 类型签名严格,非标字段(如 reasoning_effort)需通过 extra_body 透传resp1 = client.chat.completions.create(model="hy3-preview",messages=messages,tools=tools,tool_choice="auto",extra_body={"reasoning_effort": "high"},)msg1 = resp1.choices[0].messageprint("第 1 轮 assistant.reasoning_content:", getattr(msg1, "reasoning_content", ""))print("第 1 轮 tool_calls:", msg1.tool_calls)
import OpenAI from 'openai';const client = new OpenAI({apiKey: 'YOUR_API_KEY',baseURL: 'https://tokenhub.tencentmaas.com/v1',});const tools = [{type: 'function',function: {name: 'get_weather',description: '获取某地天气信息,输入 location。',parameters: {type: 'object',properties: { location: { type: 'string' } },required: ['location'],},},}];const messages = [{ role: 'system', content: '你是一个 Agent,必须按步骤推理并调用工具完成任务。' },{ role: 'user', content: '深圳今天天气怎么样?' },];const resp1 = await client.chat.completions.create({model: 'hy3-preview',messages,tools,tool_choice: 'auto',reasoning_effort: 'high',});const msg1 = resp1.choices[0].message;console.log('第 1 轮 reasoning_content:', msg1.reasoning_content);console.log('第 1 轮 tool_calls:', msg1.tool_calls);
import okhttp3.*;import com.google.gson.*;import java.util.*;public class InterleavedThinking {static final String URL = "https://tokenhub.tencentmaas.com/v1/chat/completions";static final String API_KEY = "YOUR_API_KEY";static final OkHttpClient HTTP = new OkHttpClient();static final Gson GSON = new Gson();/** 通用 chat 调用,返回原始 JSON 响应字符串。 */static String chat(List<Map<String, Object>> messages, List<Map<String, Object>> tools) throws Exception {Map<String, Object> body = new HashMap<>();body.put("model", "hy3-preview");body.put("messages", messages);body.put("tools", tools);body.put("tool_choice", "auto");body.put("reasoning_effort", "high");body.put("stream", false);Request req = new Request.Builder().url(URL).header("Authorization", "Bearer " + API_KEY).post(RequestBody.create(GSON.toJson(body), MediaType.parse("application/json"))).build();try (Response resp = HTTP.newCall(req).execute()) {return resp.body().string();}}public static void main(String[] args) throws Exception {List<Map<String, Object>> tools = List.of(Map.of("type", "function","function", Map.of("name", "get_weather","description", "获取某地天气信息,输入 location。","parameters", Map.of("type", "object","properties", Map.of("location", Map.of("type", "string")),"required", List.of("location")))));List<Map<String, Object>> messages = new ArrayList<>();messages.add(Map.of("role", "system", "content", "你是一个 Agent,必须按步骤推理并调用工具完成任务。"));messages.add(Map.of("role", "user", "content", "深圳今天天气怎么样?"));// 第 1 轮:模型决定是否调用工具String r1 = chat(messages, tools);System.out.println("第 1 轮响应:" + r1);// 接下来按响应里的 reasoning_content / tool_calls 回填到 messages,参见第 2 步}}
package mainimport ("bytes""encoding/json""fmt""io""net/http")const (URL = "https://tokenhub.tencentmaas.com/v1/chat/completions"APIKEY = "YOUR_API_KEY")// 通用 chat 调用func chat(messages []map[string]interface{}, tools []map[string]interface{}) (map[string]interface{}, error) {body, _ := json.Marshal(map[string]interface{}{"model": "hy3-preview","messages": messages,"tools": tools,"tool_choice": "auto","reasoning_effort": "high","stream": false,})req, _ := http.NewRequest("POST", URL, bytes.NewBuffer(body))req.Header.Set("Authorization", "Bearer "+APIKEY)req.Header.Set("Content-Type", "application/json")resp, err := http.DefaultClient.Do(req)if err != nil {return nil, err}defer resp.Body.Close()data, _ := io.ReadAll(resp.Body)var out map[string]interface{}json.Unmarshal(data, &out)return out, nil}func main() {tools := []map[string]interface{}{{"type": "function","function": map[string]interface{}{"name": "get_weather","description": "获取某地天气信息,输入 location。","parameters": map[string]interface{}{"type": "object","properties": map[string]interface{}{"location": map[string]string{"type": "string"},},"required": []string{"location"},},},}}messages := []map[string]interface{}{{"role": "system", "content": "你是一个 Agent,必须按步骤推理并调用工具完成任务。"},{"role": "user", "content": "深圳今天天气怎么样?"},}// 第 1 轮:模型决定是否调用工具r1, _ := chat(messages, tools)fmt.Printf("第 1 轮响应: %+v\\n", r1)// 接下来按响应里的 reasoning_content / tool_calls 回填到 messages,参见第 2 步}
响应:
{"id": "31be91fe574e41e49616352366b4fa1b","object": "chat.completion","created": 1776057110,"model": "hy3-preview","choices": [{"index": 0,"message": {"role": "assistant","content": "我来帮你查询深圳今天的天气情况。","reasoning_content": "用户问的是\\"深圳今天天气怎么样?\\",这是一个简单的天气查询请求。我需要使用get_weather函数来获取深圳的天气信息。根据函数描述,这个函数需要一个location参数,用户已经明确提供了\\"深圳\\"作为地点。所以,我应该直接调用get_weather函数,参数location设为\\"深圳\\"。不需要额外的推理步骤,因为用户的问题很直接。现在,我准备调用函数。","tool_calls": [{"id": "chatcmpl-tool-b39c6375f812783a","type": "function","function": {"name": "get_weather","arguments": "{\\"location\\": \\"深圳\\"}"}}]},"finish_reason": "tool_calls"}],"usage": {"prompt_tokens": 209,"completion_tokens": 111,"total_tokens": 320}}
第 2 轮 - 回填工具结果(在同一轮中延续思维链):
假设工具执行返回的结果为:
Cloudy,气温 7~13°C。您需要在请求中,回填工具执行结果,同时保留首次请求中响应体里获取的 reasoning_content。请求:
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy3-preview","messages": [{ "role": "system", "content": "你是一个 Agent,必须按步骤推理并调用工具完成任务。" },{ "role": "user", "content": "深圳今天天气怎么样?" },{"role": "assistant","content": "我来帮你查询深圳今天的天气情况。","reasoning_content": "用户问的是\\"深圳今天天气怎么样?\\"...","tool_calls": [{"id": "chatcmpl-tool-b39c6375f812783a","type": "function","function": {"name": "get_weather","arguments": "{\\"location\\": \\"深圳\\"}"}}]},{"role": "tool","tool_call_id": "chatcmpl-tool-b39c6375f812783a","content": "Cloudy,气温 7~13°C"}],"stream": false,"tool_choice": "auto","reasoning_effort": "high","tools": [{"type": "function","function": {"name": "get_weather","description": "获取某地天气信息,输入 location。","parameters": {"type": "object","properties": { "location": { "type": "string" } },"required": ["location"]}}}]}'
# 接续上一步:把第 1 轮的 assistant 消息(含 reasoning_content + tool_calls)# 与工具结果一起回填到 messagesimport json# 第 1 轮 assistant 消息的回写:reasoning_content 必须保留assistant_msg = {"role": "assistant","content": msg1.content,"reasoning_content": getattr(msg1, "reasoning_content", ""),"tool_calls": [{"id": tc.id,"type": tc.type,"function": {"name": tc.function.name,"arguments": tc.function.arguments,},} for tc in (msg1.tool_calls or [])],}messages.append(assistant_msg)# 业务侧执行工具,把结果以 role=tool 回填for tc in (msg1.tool_calls or []):args = json.loads(tc.function.arguments)# 这里替换为真实业务逻辑tool_result = "Cloudy,气温 7~13°C"messages.append({"role": "tool","tool_call_id": tc.id,"content": tool_result,})# 第 2 轮:把工具结果送回模型,模型继续思考并输出最终回答resp2 = client.chat.completions.create(model="hy3-preview",messages=messages,tools=tools,tool_choice="auto",extra_body={"reasoning_effort": "high"},)print("最终回答:", resp2.choices[0].message.content)
// 接续上一步:把第 1 轮的 assistant 消息(含 reasoning_content + tool_calls)// 与工具结果一起回填到 messagesconst assistantMsg = {role: 'assistant',content: msg1.content,reasoning_content: msg1.reasoning_content,tool_calls: msg1.tool_calls,};messages.push(assistantMsg);for (const tc of msg1.tool_calls || []) {const args = JSON.parse(tc.function.arguments);// 这里替换为真实业务逻辑const toolResult = 'Cloudy,气温 7~13°C';messages.push({role: 'tool',tool_call_id: tc.id,content: toolResult,});}const resp2 = await client.chat.completions.create({model: 'hy3-preview',messages,tools,tool_choice: 'auto',reasoning_effort: 'high',});console.log('最终回答:', resp2.choices[0].message.content);
// 接续 main():把第 1 轮 assistant 消息和工具结果回填,再发起第 2 轮请求// 完整流程示意(仅展示消息构造,HTTP 调用复用上一步的 chat() 函数)// 1. 解析第 1 轮响应JsonObject r1Obj = JsonParser.parseString(r1).getAsJsonObject();JsonObject msg1 = r1Obj.getAsJsonArray("choices").get(0).getAsJsonObject().getAsJsonObject("message");// 2. 把 assistant 消息(含 reasoning_content)整体回写到 messagesMap<String, Object> assistantEntry = new LinkedHashMap<>();assistantEntry.put("role", "assistant");assistantEntry.put("content", msg1.has("content") ? msg1.get("content").getAsString() : "");if (msg1.has("reasoning_content")) {assistantEntry.put("reasoning_content", msg1.get("reasoning_content").getAsString());}if (msg1.has("tool_calls")) {assistantEntry.put("tool_calls", GSON.fromJson(msg1.get("tool_calls"), List.class));}messages.add(assistantEntry);// 3. 业务侧执行工具,把工具结果以 role=tool 回填for (JsonElement el : msg1.getAsJsonArray("tool_calls")) {JsonObject call = el.getAsJsonObject();String toolResult = "Cloudy,气温 7~13°C"; // 这里替换为真实业务逻辑messages.add(Map.of("role", "tool","tool_call_id", call.get("id").getAsString(),"content", toolResult));}// 4. 第 2 轮:把工具结果送回模型String r2 = chat(messages, tools);System.out.println("第 2 轮响应:" + r2);
// 接续 main():把第 1 轮 assistant 消息和工具结果回填,再发起第 2 轮请求// 完整流程示意(仅展示消息构造,HTTP 调用复用上一步的 chat() 函数)// 1. 从第 1 轮响应中取出 assistant 消息msg1Wrap := r1["choices"].([]interface{})[0].(map[string]interface{})msg1 := msg1Wrap["message"].(map[string]interface{})// 2. 把 assistant 消息(含 reasoning_content)整体回写到 messagesmessages = append(messages, msg1)// 3. 业务侧执行工具,把工具结果以 role=tool 回填toolCalls, _ := msg1["tool_calls"].([]interface{})for _, c := range toolCalls {call := c.(map[string]interface{})toolResult := "Cloudy,气温 7~13°C" // 这里替换为真实业务逻辑messages = append(messages, map[string]interface{}{"role": "tool","tool_call_id": call["id"],"content": toolResult,})}// 4. 第 2 轮:把工具结果送回模型r2, _ := chat(messages, tools)fmt.Printf("第 2 轮响应: %+v\\n", r2)
响应:
之后,模型会根据实际推理结果继续输出(可能继续 tool_calls,也可能输出最终答案),在获得最终答案前,每次调用都需遵循上述流程,通过“保留 reasoning_content + 回填 tool 输出”以维持大模型的思维链。
{"id": "ae8941415e154a3c9749f0cf897469a4","object": "chat.completion","created": 1776057913,"model": "hy3-preview","choices": [{"index": 0,"message": {"role": "assistant","content": "根据查询结果,深圳今天的天气是**多云**,气温在 **7°C 到 13°C** 之间。今天天气比较凉爽,建议适当增添衣物,注意保暖哦!🧥","reasoning_content": "用户询问深圳今天的天气,我已经调用了get_weather工具获取了深圳的天气信息。结果显示是\\"Cloudy,气温 7~13°C\\"。\\n\\n现在我需要用中文回复用户,告诉他深圳今天的天气情况。天气是多云(Cloudy),气温在7到13摄氏度之间。\\n\\n我应该简洁明了地回复用户。"},"finish_reason": "stop"}],"usage": {"prompt_tokens": 340,"completion_tokens": 114,"total_tokens": 454}}
多轮对话
通过
messages 数组传递系统提示与历史对话,模型按顺序理解上下文并续接回复。消息顺序需为 system(可选)→ user → assistant → user → ...,且必须以 user 结尾。curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy3-preview","messages": [{"role": "system", "content": "你是一个专业的 AI 编程助手。"},{"role": "user", "content": "Python 中如何读取 JSON 文件?"},{"role": "assistant", "content": "可以使用内置的 json 模块:import json; with open(\\"data.json\\") as f: data = json.load(f)"},{"role": "user", "content": "如果 JSON 文件很大怎么办?"}]}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)response = client.chat.completions.create(model="hy3-preview",messages=[{"role": "system", "content": "你是一个专业的 AI 编程助手。"},{"role": "user", "content": "Python 中如何读取 JSON 文件?"},{"role": "assistant", "content": "可以使用内置的 json 模块:import json; with open('data.json') as f: data = json.load(f)"},{"role": "user", "content": "如果 JSON 文件很大怎么办?"},],)print(response.choices[0].message.content)
import okhttp3.*;import com.google.gson.Gson;import java.util.*;public class MultiTurn {public static void main(String[] args) throws Exception {Map<String, Object> body = new HashMap<>();body.put("model", "hy3-preview");body.put("messages", List.of(Map.of("role", "system", "content", "你是一个专业的 AI 编程助手。"),Map.of("role", "user", "content", "Python 中如何读取 JSON 文件?"),Map.of("role", "assistant", "content", "可以使用内置的 json 模块:import json; with open(\\"data.json\\") as f: data = json.load(f)"),Map.of("role", "user", "content", "如果 JSON 文件很大怎么办?")));Request request = new Request.Builder().url("https://tokenhub.tencentmaas.com/v1/chat/completions").header("Authorization", "Bearer YOUR_API_KEY").post(RequestBody.create(new Gson().toJson(body),MediaType.parse("application/json"))).build();try (Response response = new OkHttpClient().newCall(request).execute()) {System.out.println(response.body().string());}}}
import OpenAI from 'openai';const client = new OpenAI({apiKey: 'YOUR_API_KEY',baseURL: 'https://tokenhub.tencentmaas.com/v1',});const response = await client.chat.completions.create({model: 'hy3-preview',messages: [{ role: 'system', content: '你是一个专业的 AI 编程助手。' },{ role: 'user', content: 'Python 中如何读取 JSON 文件?' },{ role: 'assistant', content: '可以使用内置的 json 模块:import json; with open("data.json") as f: data = json.load(f)' },{ role: 'user', content: '如果 JSON 文件很大怎么办?' },],});console.log(response.choices[0].message.content);
package mainimport ("bytes""encoding/json""fmt""io""net/http")func main() {body, _ := json.Marshal(map[string]interface{}{"model": "hy3-preview","messages": []map[string]string{{"role": "system", "content": "你是一个专业的 AI 编程助手。"},{"role": "user", "content": "Python 中如何读取 JSON 文件?"},{"role": "assistant", "content": "可以使用内置的 json 模块:import json; with open(\\"data.json\\") as f: data = json.load(f)"},{"role": "user", "content": "如果 JSON 文件很大怎么办?"},},})req, _ := http.NewRequest("POST","https://tokenhub.tencentmaas.com/v1/chat/completions",bytes.NewBuffer(body))req.Header.Set("Authorization", "Bearer YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")resp, _ := http.DefaultClient.Do(req)defer resp.Body.Close()data, _ := io.ReadAll(resp.Body)fmt.Println(string(data))}
说明:
当历史对话中包含思考类响应时,回写
assistant 消息建议同时携带 content 与 reasoning_content 两个字段,避免推理上下文丢失。工具调用(Function Calling)
通过
tools 定义模型可调用的函数列表,模型在判断需要调用工具时返回 tool_calls;业务执行后将结果以 role: "tool" 消息回填,模型据此生成最终回答。curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy3-preview","messages": [{"role": "user", "content": "深圳今天天气怎么样?"}],"tools": [{"type": "function","function": {"name": "get_weather","description": "获取指定城市的当前天气信息","parameters": {"type": "object","properties": {"city": {"type": "string", "description": "城市名称,例如:北京"}},"required": ["city"]}}}],"tool_choice": "auto"}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)tools = [{"type": "function","function": {"name": "get_weather","description": "获取指定城市的当前天气信息","parameters": {"type": "object","properties": {"city": {"type": "string", "description": "城市名称,例如:北京"}},"required": ["city"],},},}]response = client.chat.completions.create(model="hy3-preview",messages=[{"role": "user", "content": "深圳今天天气怎么样?"}],tools=tools,tool_choice="auto",)print(response.choices[0].message)
import okhttp3.*;import com.google.gson.Gson;import java.util.*;public class FunctionCalling {public static void main(String[] args) throws Exception {Map<String, Object> tool = Map.of("type", "function","function", Map.of("name", "get_weather","description", "获取指定城市的当前天气信息","parameters", Map.of("type", "object","properties", Map.of("city", Map.of("type", "string", "description", "城市名称,例如:北京")),"required", List.of("city"))));Map<String, Object> body = new HashMap<>();body.put("model", "hy3-preview");body.put("messages", List.of(Map.of("role", "user", "content", "深圳今天天气怎么样?")));body.put("tools", List.of(tool));body.put("tool_choice", "auto");Request request = new Request.Builder().url("https://tokenhub.tencentmaas.com/v1/chat/completions").header("Authorization", "Bearer YOUR_API_KEY").post(RequestBody.create(new Gson().toJson(body),MediaType.parse("application/json"))).build();try (Response response = new OkHttpClient().newCall(request).execute()) {System.out.println(response.body().string());}}}
import OpenAI from 'openai';const client = new OpenAI({apiKey: 'YOUR_API_KEY',baseURL: 'https://tokenhub.tencentmaas.com/v1',});const tools = [{type: 'function',function: {name: 'get_weather',description: '获取指定城市的当前天气信息',parameters: {type: 'object',properties: { city: { type: 'string', description: '城市名称,例如:北京' } },required: ['city'],},},}];const response = await client.chat.completions.create({model: 'hy3-preview',messages: [{ role: 'user', content: '深圳今天天气怎么样?' }],tools,tool_choice: 'auto',});console.log(response.choices[0].message);
package mainimport ("bytes""encoding/json""fmt""io""net/http")func main() {tool := map[string]interface{}{"type": "function","function": map[string]interface{}{"name": "get_weather","description": "获取指定城市的当前天气信息","parameters": map[string]interface{}{"type": "object","properties": map[string]interface{}{"city": map[string]interface{}{"type": "string", "description": "城市名称,例如:北京"},},"required": []string{"city"},},},}body, _ := json.Marshal(map[string]interface{}{"model": "hy3-preview","messages": []map[string]string{{"role": "user", "content": "深圳今天天气怎么样?"}},"tools": []map[string]interface{}{tool},"tool_choice": "auto",})req, _ := http.NewRequest("POST","https://tokenhub.tencentmaas.com/v1/chat/completions",bytes.NewBuffer(body))req.Header.Set("Authorization", "Bearer YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")resp, _ := http.DefaultClient.Do(req)defer resp.Body.Close()data, _ := io.ReadAll(resp.Body)fmt.Println(string(data))}
模型决定调用工具时的响应:
{"id": "REPLACED_ID","object": "chat.completion","model": "hy3-preview","created": 1775146513,"choices": [{"index": 0,"message": {"role": "assistant","content": "我来帮你查询深圳今天的天气情况。","tool_calls": [{"id": "REPLACED_ID","type": "function","function": {"name": "get_weather","arguments": "{\\"city\\": \\"深圳\\"}"}}]},"finish_reason": "tool_calls"}],"usage": {"prompt_tokens": 208,"completion_tokens": 28,"total_tokens": 236,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens_details": {"reasoning_tokens": 0}}}
回填工具执行结果继续对话:
{"model": "hy3-preview","messages": [{"role": "user", "content": "深圳今天天气怎么样?"},{"role": "assistant","content": "我来帮您查询深圳今天的天气情况。","tool_calls": [{"id": "REPLACED_ID","type": "function","function": {"name": "get_weather", "arguments": "{\\"city\\": \\"深圳\\"}"}}]},{"role": "tool","tool_call_id": "REPLACED_ID","content": "{\\"temperature\\":28,\\"weather\\":\\"晴\\",\\"humidity\\":\\"65%\\"}"}]}
注意:
在
reasoning_effort=low/high 的慢思考模式下进行工具调用,每一轮请求都需要回填历史 reasoning_content,以获取最佳效果。结构化输出
通过
response_format 约束模型按指定的 JSON Schema 输出,常用于信息抽取、结构化数据生成等场景。curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy3-preview","messages": [{"role": "user", "content": "请从以下文本中提取人物信息:张三,35岁,是一名高级软件工程师,擅长Python、Java和机器学习。"}],"response_format": {"type": "json_schema","json_schema": {"name": "person_info","schema": {"type": "object","properties": {"name": {"type": "string", "description": "人物姓名"},"age": {"type": "integer", "description": "年龄"},"occupation": {"type": "string", "description": "职业"},"skills": {"type": "array", "items": {"type": "string"}, "description": "技能列表"}},"required": ["name", "age", "occupation", "skills"]}}}}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)schema = {"type": "object","properties": {"name": {"type": "string", "description": "人物姓名"},"age": {"type": "integer", "description": "年龄"},"occupation": {"type": "string", "description": "职业"},"skills": {"type": "array", "items": {"type": "string"}, "description": "技能列表"},},"required": ["name", "age", "occupation", "skills"],}response = client.chat.completions.create(model="hy3-preview",messages=[{"role": "user", "content": "请从以下文本中提取人物信息:张三,35岁,是一名高级软件工程师,擅长Python、Java和机器学习。"},],response_format={"type": "json_schema","json_schema": {"name": "person_info", "schema": schema},},)print(response.choices[0].message.content)
import okhttp3.*;import com.google.gson.Gson;import java.util.*;public class StructuredOutput {public static void main(String[] args) throws Exception {Map<String, Object> schema = Map.of("type", "object","properties", Map.of("name", Map.of("type", "string", "description", "人物姓名"),"age", Map.of("type", "integer", "description", "年龄"),"occupation", Map.of("type", "string", "description", "职业"),"skills", Map.of("type", "array", "items", Map.of("type", "string"), "description", "技能列表")),"required", List.of("name", "age", "occupation", "skills"));Map<String, Object> body = new HashMap<>();body.put("model", "hy3-preview");body.put("messages", List.of(Map.of("role", "user", "content","请从以下文本中提取人物信息:张三,35岁,是一名高级软件工程师,擅长Python、Java和机器学习。")));body.put("response_format", Map.of("type", "json_schema","json_schema", Map.of("name", "person_info", "schema", schema)));Request request = new Request.Builder().url("https://tokenhub.tencentmaas.com/v1/chat/completions").header("Authorization", "Bearer YOUR_API_KEY").post(RequestBody.create(new Gson().toJson(body),MediaType.parse("application/json"))).build();try (Response response = new OkHttpClient().newCall(request).execute()) {System.out.println(response.body().string());}}}
import OpenAI from 'openai';const client = new OpenAI({apiKey: 'YOUR_API_KEY',baseURL: 'https://tokenhub.tencentmaas.com/v1',});const schema = {type: 'object',properties: {name: { type: 'string', description: '人物姓名' },age: { type: 'integer', description: '年龄' },occupation: { type: 'string', description: '职业' },skills: { type: 'array', items: { type: 'string' }, description: '技能列表' },},required: ['name', 'age', 'occupation', 'skills'],};const response = await client.chat.completions.create({model: 'hy3-preview',messages: [{ role: 'user', content: '请从以下文本中提取人物信息:张三,35岁,是一名高级软件工程师,擅长Python、Java和机器学习。' },],response_format: {type: 'json_schema',json_schema: { name: 'person_info', schema },},});console.log(response.choices[0].message.content);
package mainimport ("bytes""encoding/json""fmt""io""net/http")func main() {schema := map[string]interface{}{"type": "object","properties": map[string]interface{}{"name": map[string]interface{}{"type": "string", "description": "人物姓名"},"age": map[string]interface{}{"type": "integer", "description": "年龄"},"occupation": map[string]interface{}{"type": "string", "description": "职业"},"skills": map[string]interface{}{"type": "array", "items": map[string]string{"type": "string"}, "description": "技能列表",},},"required": []string{"name", "age", "occupation", "skills"},}body, _ := json.Marshal(map[string]interface{}{"model": "hy3-preview","messages": []map[string]string{{"role": "user", "content": "请从以下文本中提取人物信息:张三,35岁,是一名高级软件工程师,擅长Python、Java和机器学习。"},},"response_format": map[string]interface{}{"type": "json_schema","json_schema": map[string]interface{}{"name": "person_info","schema": schema,},},})req, _ := http.NewRequest("POST","https://tokenhub.tencentmaas.com/v1/chat/completions",bytes.NewBuffer(body))req.Header.Set("Authorization", "Bearer YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")resp, _ := http.DefaultClient.Do(req)defer resp.Body.Close()data, _ := io.ReadAll(resp.Body)fmt.Println(string(data))}
响应示例:
{"id": "REPLACED_ID","object": "chat.completion","model": "hy3-preview","created": 1775146513,"choices": [{"index": 0,"message": {"role": "assistant","content": "{\\n \\"age\\": 35,\\n \\"name\\": \\"张三\\",\\n \\"occupation\\": \\"高级软件工程师\\",\\n \\"skills\\": [\\"Python\\", \\"Java\\", \\"机器学习\\"]\\n}"},"finish_reason": "stop"}],"usage": {"prompt_tokens": 38,"completion_tokens": 42,"total_tokens": 80,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens_details": {"reasoning_tokens": 0}}}
翻译模型
Hy-MT2 是一款面向真实复杂场景的“快思考”多语言翻译模型家族,包含 1.8B、7B、30B-A3B(MoE)三种体量,支持 33 个语种之间的互译,并能高效遵循多语言翻译指令。多维度评测显示,Hy-MT2 在通用翻译、真实业务场景翻译、垂直领域翻译以及指令遵循翻译等任务上均表现出色。
基础翻译
最常见的翻译场景,在
user 消息中明确指定目标语种(target_lang 使用完整中文名,如“中文”、“英语”)。"messages": {"role": "user", "content": "将以下文本翻译为 {target_lang},注意只需要输出翻译后的结果,不要额外解释:{source_text}"}
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy-mt2-pro","messages": [{"role": "user", "content": "将以下文本翻译为 英语 ,注意只需要输出翻译后的结果,不要额外解释: 腾讯混元大模型已上线 TokenHub 平台,支持深度思考、结构化输出、Function Calling 等能力。"}]}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)target_lang = "英语"source_text = "腾讯混元大模型已上线 TokenHub 平台,支持深度思考、结构化输出、Function Calling 等能力。"prompt = f"""将以下文本翻译为 {target_lang},注意只需要输出翻译后的结果,不要额外解释:{source_text}"""response = client.chat.completions.create(model="hy-mt2-pro",messages=[{"role": "user", "content": prompt}],)print(response.choices[0].message.content)
import okhttp3.*;import com.google.gson.Gson;import java.util.*;public class TranslationDemo {public static void main(String[] args) throws Exception {String targetLang = "英语";String sourceText = "腾讯混元大模型已上线 TokenHub 平台,支持深度思考、结构化输出、Function Calling 等能力。";String prompt = "将以下文本翻译为 " + targetLang + ",注意只需要输出翻译后的结果,不要额外解释:\\n" + sourceText;Map<String, Object> body = new HashMap<>();body.put("model", "hy-mt2-pro");body.put("messages", List.of(Map.of("role", "user", "content", prompt)));Request request = new Request.Builder().url("https://tokenhub.tencentmaas.com/v1/chat/completions").header("Authorization", "Bearer YOUR_API_KEY").post(RequestBody.create(new Gson().toJson(body),MediaType.parse("application/json"))).build();try (Response response = new OkHttpClient().newCall(request).execute()) {System.out.println(response.body().string());}}}
import OpenAI from 'openai';const client = new OpenAI({apiKey: 'YOUR_API_KEY',baseURL: 'https://tokenhub.tencentmaas.com/v1',});const targetLang = '英语';const sourceText = '腾讯混元大模型已上线 TokenHub 平台,支持深度思考、结构化输出、Function Calling 等能力。';const prompt = `将以下文本翻译为 ${targetLang},注意只需要输出翻译后的结果,不要额外解释:\\n${sourceText}`;const response = await client.chat.completions.create({model: 'hy-mt2-pro',messages: [{ role: 'user', content: prompt }],});console.log(response.choices[0].message.content);
package mainimport ("bytes""encoding/json""fmt""io""net/http")func main() {targetLang := "英语"sourceText := "腾讯混元大模型已上线 TokenHub 平台,支持深度思考、结构化输出、Function Calling 等能力。"prompt := "将以下文本翻译为 " + targetLang + ",注意只需要输出翻译后的结果,不要额外解释:\\n" + sourceTextbody, _ := json.Marshal(map[string]interface{}{"model": "hy-mt2-pro","messages": []map[string]string{{"role": "user", "content": prompt},},})req, _ := http.NewRequest("POST","https://tokenhub.tencentmaas.com/v1/chat/completions",bytes.NewBuffer(body))req.Header.Set("Authorization", "Bearer YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")resp, _ := http.DefaultClient.Do(req)defer resp.Body.Close()data, _ := io.ReadAll(resp.Body)fmt.Println(string(data))}
响应示例:
{"id": "REPLACED_ID","object": "chat.completion","model": "hy-mt2-pro","created": 1775146513,"choices": [{"index": 0,"message": {"role": "assistant","content": "The Tencent Hunyuan large model is now available on the TokenHub platform. It supports capabilities such as deep reasoning, structured output, and Function Calling."},"finish_reason": "stop"}],"usage": {"prompt_tokens": 57,"completion_tokens": 32,"total_tokens": 89,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens_details": {"reasoning_tokens": 0}}}
结构化数据翻译
当原文是 JSON / Markdown / HTML / XML 等结构化数据时,模型会“锁定结构、仅翻译可见 value、保留所有 key 与占位符”。
"messages": {"role": "user", "content": "# 任务目标将下方 {source_text} 中的 {format_type} 格式数据翻译为 {target_lang}。# 严格约束1. 结构锁定:绝对保持原有的 {format_type} 数据结构、缩进和层级完全不变。2. 选择性翻译:仅翻译面向用户展示的可见文本内容。3. 禁止修改:严禁翻译或更改任何代码标签、键名 (Key)、变量占位符(如 {{var}}、${var}、%s、%d 等)或代码属性。# 数据输入{source_text}"}
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy-mt2-pro","messages": [{"role": "user", "content": "# 任务目标\\n将下方 source_text 中的 JSON 格式数据翻译为 英语。\\n\\n# 严格约束\\n1. 结构锁定:绝对保持原有的 JSON 数据结构、缩进和层级完全不变。\\n2. 选择性翻译:仅翻译面向用户展示的可见文本内容。\\n3. 禁止修改:严禁翻译或更改任何代码标签、键名 (Key)、变量占位符(如 {{var}}、${var}、%s、%d 等)或代码属性。\\n\\n# 数据输入\\n{\\"title\\": \\"产品介绍\\", \\"description\\": \\"腾讯混元大模型已上线 TokenHub 平台\\", \\"tags\\": [\\"大模型\\", \\"翻译\\", \\"AI\\"]}"}]}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)target_lang = "英语"format_type = "JSON"source_text = '{"title": "产品介绍", "description": "腾讯混元大模型已上线 TokenHub 平台", "tags": ["大模型", "翻译", "AI"]}'prompt = f"""# 任务目标将下方 source_text 中的 {format_type} 格式数据翻译为 {target_lang}。# 严格约束1. 结构锁定:绝对保持原有的 {format_type} 数据结构、缩进和层级完全不变。2. 选择性翻译:仅翻译面向用户展示的可见文本内容。3. 禁止修改:严禁翻译或更改任何代码标签、键名 (Key)、变量占位符(如 {{var}}、${{var}}、%s、%d 等)或代码属性。# 数据输入{source_text}"""response = client.chat.completions.create(model="hy-mt2-pro",messages=[{"role": "user", "content": prompt}],)print(response.choices[0].message.content)
响应示例:
{"id": "REPLACED_ID","object": "chat.completion","model": "hy-mt2-pro","created": 1779966611,"choices": [{"index": 0,"message": {"role": "assistant","content": "{\\"title\\": \\"Product Introduction\\", \\"description\\": \\"Tencent Hunyuan Large Model is now available on the TokenHub platform.\\", \\"tags\\": [\\"Large Model\\", \\"Translation\\", \\"AI\\"]}"},"finish_reason": "stop"}],"usage": {"prompt_tokens": 158,"completion_tokens": 41,"total_tokens": 199,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens_details": {"reasoning_tokens": 0}}}
分隔符翻译
需要逐句对照或批量翻译多段文本时,让模型保留等量的分隔符且不遗漏、不转义、不翻译,便于业务侧按下标对齐。
推荐使用
<SEP>、### 等不会与目标语言标点冲突的标签作为分隔符。|||、--- 等容易被部分语言识别为感叹号、破折号等标点,导致译文不可切分。"messages": {"role": "user", "content": "请将以下文本准确翻译为 {target_lang}。你必须在译文中保留等量的分隔符,绝对不可遗漏、转义或翻译该符号,并注意分隔符的位置。{source_text}"}
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy-mt2-pro","messages": [{"role": "user", "content": "请将以下文本准确翻译为 英语。你必须在译文中保留等量的分隔符,绝对不可遗漏、转义或翻译该符号,并注意分隔符的位置。\\n腾讯混元大模型已上线<SEP>支持深度思考与工具调用<SEP>覆盖 38 种语言互译"}]}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)target_lang = "英语"SEP = "<SEP>"source_segments = ["腾讯混元大模型已上线", "支持深度思考与工具调用", "覆盖 38 种语言互译"]source_text = SEP.join(source_segments)prompt = f"""请将以下文本准确翻译为 {target_lang}。你必须在译文中保留等量的分隔符,绝对不可遗漏、转义或翻译该符号,并注意分隔符的位置。{source_text}"""response = client.chat.completions.create(model="hy-mt2-pro",messages=[{"role": "user", "content": prompt}],)translated = response.choices[0].message.content.split(SEP)for src, tgt in zip(source_segments, translated):print(f"{src.strip()} → {tgt.strip()}")
响应示例:
{"id": "REPLACED_ID","object": "chat.completion","model": "hy-mt2-pro","created": 1779966612,"choices": [{"index": 0,"message": {"role": "assistant","content": "Tencent Hunyuan large model is now live <SEP> Supports deep reasoning and tool invocation <SEP> Covers translation between 38 languages"},"finish_reason": "stop"}],"usage": {"prompt_tokens": 77,"completion_tokens": 31,"total_tokens": 108,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens_details": {"reasoning_tokens": 0}}}
上下文翻译
当原文存在多义词、专有名词、代词指代等需要语境消歧的情况时,提供“背景信息”可以让模型选用与上下文一致的术语。
"messages": {"role": "user", "content": "【背景信息】{background_text}请结合背景信息将以下文本翻译为 {target_lang}。【待翻译文本】{source_text}"}
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy-mt2-pro","messages": [{"role": "user", "content": "【背景信息】\\n这是一篇介绍数据库系统的技术文档,上文提到的 transaction 指数据库事务,index 指数据库索引。\\n请结合背景信息将以下文本翻译为 英语。\\n【待翻译文本】\\n事务提交后,索引会被异步刷新到磁盘。"}]}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)target_lang = "英语"background_text = "这是一篇介绍数据库系统的技术文档,上文提到的 transaction 指数据库事务,index 指数据库索引。"source_text = "事务提交后,索引会被异步刷新到磁盘。"prompt = f"""【背景信息】{background_text}请结合背景信息将以下文本翻译为 {target_lang}。【待翻译文本】{source_text}"""response = client.chat.completions.create(model="hy-mt2-pro",messages=[{"role": "user", "content": prompt}],)print(response.choices[0].message.content)
响应示例:
{"id": "REPLACED_ID","object": "chat.completion","model": "hy-mt2-pro","created": 1779966614,"choices": [{"index": 0,"message": {"role": "assistant","content": "After a transaction is committed, the index is asynchronously flushed to disk."},"finish_reason": "stop"}],"usage": {"prompt_tokens": 68,"completion_tokens": 15,"total_tokens": 83,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens_details": {"reasoning_tokens": 0}}}
术语表翻译
业务侧拥有领域术语表(产品名、品牌词、专有名词等需固定译法)时,将术语对照清单作为参考前置,模型会优先按指定译法翻译。
"messages": {"role": "user", "content": "参考下面的翻译:{text} 翻译成 {text}{text} 翻译成 {text}{text} 翻译成 {text}将以下文本翻译为 {target_lang},注意只需要输出翻译后的结果,不要额外解释:{source_text}"}
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy-mt2-pro","messages": [{"role": "user", "content": "参考下面的翻译:\\n混元大模型 翻译成 Tencent Hy\\n腾讯云 翻译成 Tencent Cloud\\n深度思考 翻译成 deep reasoning\\n将以下文本翻译为 英语,注意只需要输出翻译后的结果,不要额外解释:\\n腾讯云上的混元大模型支持深度思考能力。"}]}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)target_lang = "英语"glossary = [("混元大模型", "Tencent Hy"),("腾讯云", "Tencent Cloud"),("深度思考", "deep reasoning"),]source_text = "腾讯云上的混元大模型支持深度思考能力。"glossary_text = "\\n".join(f"{src} 翻译成 {tgt}" for src, tgt in glossary)prompt = f"""参考下面的翻译:{glossary_text}将以下文本翻译为 {target_lang},注意只需要输出翻译后的结果,不要额外解释:{source_text}"""response = client.chat.completions.create(model="hy-mt2-pro",messages=[{"role": "user", "content": prompt}],)print(response.choices[0].message.content)
响应示例:
{"id": "REPLACED_ID","object": "chat.completion","model": "hy-mt2-pro","created": 1779967706,"choices": [{"index": 0,"message": {"role": "assistant","content": "Tencent Hy on Tencent Cloud supports deep reasoning capabilities."},"finish_reason": "stop"}],"usage": {"prompt_tokens": 72,"completion_tokens": 13,"total_tokens": 85,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens_details": {"reasoning_tokens": 0}}}
风格翻译
不同业务场景对译文风格要求不同(口语化 / 书面化 / 营销文案 / 法律合同 / 学术 / 古文等),描述出目标风格,模型会按要求调整用词与句式。
"messages": {"role": "user", "content": "请将以下文本翻译为 {target_lang}。注意翻译的风格要严格符合【{target_style}】{source_text}"}
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-d '{"model": "hy-mt2-pro","messages": [{"role": "user", "content": "请将以下文本翻译为 英语。注意翻译的风格要严格符合【营销文案:语言简洁有力、富有感染力、突出卖点,适合面向海外开发者的产品介绍】\\n腾讯混元大模型,开箱即用,让 AI 应用开发更简单。"}]}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)target_lang = "英语"target_style = "营销文案:语言简洁有力、富有感染力、突出卖点,适合面向海外开发者的产品介绍"source_text = "腾讯混元大模型,开箱即用,让 AI 应用开发更简单。"prompt = f"""请将以下文本翻译为 {target_lang}。注意翻译的风格要严格符合【{target_style}】{source_text}"""response = client.chat.completions.create(model="hy-mt2-pro",messages=[{"role": "user", "content": prompt}],)print(response.choices[0].message.content)
响应示例:
{"id": "REPLACED_ID","object": "chat.completion","model": "hy-mt2-pro","created": 1779966617,"choices": [{"index": 0,"message": {"role": "assistant","content": "Tencent Hunyuan Large Model is ready to use right out of the box, making AI application development easier than ever."},"finish_reason": "stop"}],"usage": {"prompt_tokens": 66,"completion_tokens": 25,"total_tokens": 91,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens_details": {"reasoning_tokens": 0}}}
支持的语言
语言 | 英文名 | 代码 |
简体中文 | Chinese | zh |
繁体中文 | Traditional Chinese | zh-Hant |
英语 | English | en |
法语 | French | fr |
葡萄牙语 | Portuguese | pt |
西班牙语 | Spanish | es |
日语 | Japanese | ja |
土耳其语 | Turkish | tr |
俄语 | Russian | ru |
阿拉伯语 | Arabic | ar |
韩语 | Korean | ko |
泰语 | Thai | th |
意大利语 | Italian | it |
德语 | German | de |
越南语 | Vietnamese | vi |
马来语 | Malay | ms |
印尼语 | Indonesian | id |
菲律宾语 | Filipino | tl |
印地语 | Hindi | hi |
波兰语 | Polish | pl |
捷克语 | Czech | cs |
荷兰语 | Dutch | nl |
高棉语 | Khmer | km |
缅甸语 | Burmese | my |
波斯语 | Persian | fa |
古吉拉特语 | Gujarati | gu |
乌尔都语 | Urdu | ur |
泰卢固语 | Telugu | te |
马拉地语 | Marathi | mr |
希伯来语 | Hebrew | he |
孟加拉语 | Bengali | bn |
泰米尔语 | Tamil | ta |
乌克兰语 | Ukrainian | uk |
藏语 | Tibetan | bo |
哈萨克语 | Kazakh | kk |
蒙古语 | Mongolian | mn |
维吾尔语 | Uyghur | ug |
粤语 | Cantonese | yue |
角色扮演模型
hunyuan-role-latest 是混元的角色扮演模型,适用于 AI 数字分身、AI 角色扮演、AI 情感陪聊等场景。建议在 system 中给出清晰的人设描述(背景/性格/语言风格/禁忌),多轮对话中模型会保持人设一致性。curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-H 'Content-Type: application/json' \\-d '{"model": "hunyuan-role-latest","messages": [{"role": "system", "content": "你叫小溪,是一名性格温柔、有耐心的咖啡店店员,喜欢和客人轻松聊天。请保持自然口语化的中文回复,不要承认自己是 AI。"},{"role": "user", "content": "今天工作好累,想喝杯什么提提神?"}]}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1",)response = client.chat.completions.create(model="hunyuan-role-latest",messages=[{"role": "system","content": "你叫小溪,是一名性格温柔、有耐心的咖啡店店员,喜欢和客人轻松聊天。请保持自然口语化的中文回复,不要承认自己是 AI。",},{"role": "user", "content": "今天工作好累,想喝杯什么提提神?"},],)print(response.choices[0].message.content)
响应示例:
{"id": "REPLACED_ID","object": "chat.completion","model": "hunyuan-role-latest","created": 1775146513,"choices": [{"index": 0,"message": {"role": "assistant","content": "那你试试美式吧,苦中带点香,一口下去超提神的!(歪头思索片刻,眼睛亮晶晶地看着你)或者你喜欢甜一点的话,拿铁也不错哦。"},"finish_reason": "stop"}],"usage": {"prompt_tokens": 52,"completion_tokens": 44,"total_tokens": 96,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens_details": {"reasoning_tokens": 0}}}
视觉与多模态模型指引
本文中的混元语言模型不支持图片、视频等多模态输入。如需多模态能力,请改用对应的视觉模型、多模态理解模型,调用方式与请求格式请参见各专项文档:
图像生成
视频生成
3D 生成
多模态理解
错误处理与调试建议
错误码:API 报错请参见 API 错误码说明。
思考模式调试:使用
hy3-preview 时,如果只看到空响应或被截断,请优先检查 max_tokens 是否设置过小(思考模型的推理 + 回答共享 token 额度,建议 ≥ 16000)。请参见 深度思考、交错式思考模式。流式超时:长输出场景建议开启
stream: true,避免网关侧超时。