Skip to main content
QwenCloud home page
Docs
Specialized models

Intent understanding

Identify user intent and select tools in milliseconds with tongyi-intent-detect-v3

tongyi-intent-detect-v3 identifies a user's intent and selects the tool that can handle the request. It returns results in milliseconds, which makes it suitable for routing requests in voice assistants, customer service bots, and agent pipelines. Key capabilities:
  • Millisecond intent parsing: classifies intent in a few hundred milliseconds.
  • Tool selection: matches a user request to the appropriate tool and returns the tool call.
  • Multi-turn conversations: asks follow-up questions when the request lacks the information a tool needs.
Supported regions: China North 2 (Beijing) only. Use an API key created in that region and https://cn-beijing.maas.qwencloudapi.com. See Regions and endpoints.

Supported models

ModelContextMax inputMax outputInput priceOutput price
tongyi-intent-detect-v38,1928,1921,024$0.058 per 1M tokens$0.144 per 1M tokens
For billing details, see Model pricing.

How it works

The model supports three modes, selected by a keyword in the system message:
ModeSystem message keywordResponse
Intent and function callResponse in INTENT_MODE.Intent tags, tool call, and reply content
Intent onlyA tag list plus Just reply with the chosen tag.A single tag
Function call onlyResponse in NORMAL_MODE.A tool call
Tools are described to the model in the system message as a JSON array. The model does not call the tools itself: you parse the response and execute the call.

Prerequisites

Get an API key and set it as an environment variable. To use an SDK, install it.

Output intent and function call information

To return intent tags, the tool call, and reply content in one response, set the system message as follows: 
You are a helpful assistant. You may call one or more tools to assist with the user query. The tools you can use are as follows:
{Tool information}
Response in INTENT_MODE.
The tool information is a JSON array: 
[
  {
    "name": "Name of tool 1",
    "description": "Description of tool 1",
    "parameters": {
      "type": "object",
      "properties": {
        "parameter_1": {
          "description": "Description of parameter_1",
          "type": "Type of parameter_1"
        }
      },
      "required": ["parameter_1"]
    }
  }
]
This example defines two tools, one for the current time and one for the weather: 
[
  {
    "name": "get_current_time",
    "description": "This is useful when you want to know the current time.",
    "parameters": {}
  },
  {
    "name": "get_current_weather",
    "description": "This is useful when you want to query the weather of a specified city.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "A city or district, such as Beijing, Hangzhou, or Yuhang District."
        }
      },
      "required": ["location"]
    }
  }
]

Sample request

  • OpenAI compatible
  • DashScope
import os
import json
from openai import OpenAI

tools = [
  {
    "name": "get_current_time",
    "description": "This is useful when you want to know the current time.",
    "parameters": {}
  },
  {
    "name": "get_current_weather",
    "description": "This is useful when you want to query the weather of a specified city.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "A city or district, such as Beijing, Hangzhou, or Yuhang District."
        }
      },
      "required": ["location"]
    }
  }
]

tools_string = json.dumps(tools, ensure_ascii=False)

system_prompt = f"""You are a helpful assistant. You may call one or more tools to assist with the user query. The tools you can use are as follows:
{tools_string}
Response in INTENT_MODE."""

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://cn-beijing.maas.qwencloudapi.com/compatible-mode/v1",
)

messages = [
  {"role": "system", "content": system_prompt},
  {"role": "user", "content": "Weather in Hangzhou"}
]

response = client.chat.completions.create(
  model="tongyi-intent-detect-v3",
  messages=messages
)

print(response.choices[0].message.content)

Sample response

<tags>
[function call, json response]
</tags><tool_call>
[{"name": "get_current_weather", "arguments": {"location": "Hangzhou"}}]
</tool_call><content>

</content>
The response has three parts:
  • tags: what the model detected in the request.
  • tool_call: a JSON array with the tools to call and their arguments. It is empty when no tool is needed.
  • content: the reply to the user, empty when the model only calls a tool.

Parse the response

import re
import json


def parse_text(text):
  # Match <tags>, <tool_call>, and <content>
  tags_pattern = r"<tags>(.*?)</tags>"
  tool_call_pattern = r"<tool_call>(.*?)</tool_call>"
  content_pattern = r"<content>(.*?)</content>"

  tags_match = re.search(tags_pattern, text, re.DOTALL)
  tool_call_match = re.search(tool_call_pattern, text, re.DOTALL)
  content_match = re.search(content_pattern, text, re.DOTALL)

  tags = tags_match.group(1).strip() if tags_match else ""
  tool_call = tool_call_match.group(1).strip() if tool_call_match else ""
  content = content_match.group(1).strip() if content_match else ""

  return {
    "tags": tags,
    "tool_call": json.loads(tool_call) if tool_call else [],
    "content": content
  }


response = """<tags>
[function call, json response]
</tags><tool_call>
[{"name": "get_current_weather", "arguments": {"location": "Hangzhou"}}]
</tool_call><content>

</content>"""

print(parse_text(response))
Output: 
{
  "tags": "[function call, json response]",
  "tool_call": [
    {
      "name": "get_current_weather",
      "arguments": {
        "location": "Hangzhou"
      }
    }
  ],
  "content": ""
}

Output only intent information

To classify the request into one of your own intent categories, list them in the system message: 
You are a helpful assistant.
You should choose one tag from the tag list:
{Intent information}
Just reply with the chosen tag.
The intent information maps each tag to a description: 
{
  "Intent 1": "Description of Intent 1",
  "Intent 2": "Description of Intent 2",
  "Intent 3": "Description of Intent 3"
}

Sample request

  • OpenAI compatible
  • DashScope
import os
import json
from openai import OpenAI

intent_dict = {
  "play_game": "Play game",
  "email_querycontact": "Email query contact",
  "general_quirky": "quirky",
  "email_addcontact": "Email add contact",
  "takeaway_query": "Takeaway query",
  "recommendation_locations": "Location recommendation",
  "transport_traffic": "Transportation",
  "iot_cleaning": "IoT - vacuum cleaner, cleaner",
  "general_joke": "Joke",
  "lists_query": "Query list/checklist",
  "calendar_remove": "Calendar delete event",
  "transport_taxi": "Taxi, taxi booking",
  "qa_factoid": "Factual Q&A",
  "transport_ticket": "Transportation ticket",
  "play_radio": "Play radio",
  "alarm_set": "Set alarm"
}

intent_string = json.dumps(intent_dict, ensure_ascii=False)

system_prompt = f"""You are a helpful assistant.
You should choose one tag from the tag list:
{intent_string}
Just reply with the chosen tag."""

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://cn-beijing.maas.qwencloudapi.com/compatible-mode/v1",
)

messages = [
  {"role": "system", "content": system_prompt},
  {"role": "user", "content": "Wake me up at nine on Friday morning"}
]

response = client.chat.completions.create(
  model="tongyi-intent-detect-v3",
  messages=messages
)

print(response.choices[0].message.content)

Sample response

alarm_set

Improve response time

Single-token responses are faster than multi-token ones. For the lowest latency, map each intent to a single uppercase letter: 
intent_dict = {
  "A": "Play game",
  "B": "Email query contact",
  "C": "quirky",
  "D": "Email add contact",
  "E": "Takeaway query",
  "F": "Location recommendation",
  "G": "Transportation",
  "H": "IoT - vacuum cleaner, cleaner",
  "I": "Joke",
  "J": "Query list/checklist",
  "K": "Calendar delete event",
  "L": "Taxi, taxi booking",
  "M": "Factual Q&A",
  "N": "Transportation ticket",
  "O": "Play radio",
  "P": "Set alarm"
}
Use the same system message template as above. For the question "What is the earliest flight from Beijing to Hangzhou?", the model returns: 
M

Output only function call information

To return only the tool call, set the system message as follows: 
You are a helpful assistant. You may call one or more tools to assist with the user query. The tools you can use are as follows:
{Tool information}
Response in NORMAL_MODE.
The tool information uses the same format as Output intent and function call information.

Sample request

  • OpenAI compatible
  • DashScope
import os
import json
from openai import OpenAI

tools = [
  {
    "name": "get_current_time",
    "description": "This is useful when you want to know the current time.",
    "parameters": {}
  },
  {
    "name": "get_current_weather",
    "description": "This is useful when you want to query the weather of a specified city.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "A city or district, such as Beijing, Hangzhou, or Yuhang District."
        }
      },
      "required": ["location"]
    }
  }
]

tools_string = json.dumps(tools, ensure_ascii=False)

system_prompt = f"""You are a helpful assistant. You may call one or more tools to assist with the user query. The tools you can use are as follows:
{tools_string}
Response in NORMAL_MODE."""

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://cn-beijing.maas.qwencloudapi.com/compatible-mode/v1",
)

messages = [
  {"role": "system", "content": system_prompt},
  {"role": "user", "content": "Weather in Hangzhou"}
]

response = client.chat.completions.create(
  model="tongyi-intent-detect-v3",
  messages=messages
)

print(response.choices[0].message.content)

Sample response

<tool_call>
{"name": "get_current_weather", "arguments": {"location": "Hangzhou"}}
</tool_call>

Parse the response

import re


def parse_text(text):
  tool_call_pattern = r"<tool_call>(.*?)</tool_call>"
  tool_call_match = re.search(tool_call_pattern, text, re.DOTALL)
  return tool_call_match.group(1).strip() if tool_call_match else ""


response = """<tool_call>
{"name": "get_current_weather", "arguments": {"location": "Hangzhou"}}
</tool_call>"""

print(parse_text(response))
Output: 
{"name": "get_current_weather", "arguments": {"location": "Hangzhou"}}

Multi-turn conversations

When the request is missing a parameter a tool needs, the model asks a follow-up question instead of calling the tool. After the user supplies the missing information, it returns the tool call. Append each response to the message history before sending the next question.
  • Intent and function call
  • Function call only
  • OpenAI compatible
  • DashScope
import os
import json
from openai import OpenAI

tools = [
  {
    "name": "get_current_time",
    "description": "This is useful when you want to know the current time.",
    "parameters": {}
  },
  {
    "name": "get_current_weather",
    "description": "This is useful when you want to query the weather of a specified city.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "A city or district, such as Beijing, Hangzhou, or Yuhang District."
        }
      },
      "required": ["location"]
    }
  }
]

tools_string = json.dumps(tools, ensure_ascii=False)

system_prompt = f"""You are a helpful assistant. You may call one or more tools to assist with the user query. The tools you can use are as follows:
{tools_string}
Response in INTENT_MODE."""

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://cn-beijing.maas.qwencloudapi.com/compatible-mode/v1",
)

messages = [
  {"role": "system", "content": system_prompt},
  {"role": "user", "content": "I want to check the weather"}
]

response = client.chat.completions.create(
  model="tongyi-intent-detect-v3",
  messages=messages
)

print("Query: I want to check the weather")
print("First-round output:\n")
print(response.choices[0].message.content)

messages.append(response.choices[0].message)
messages.append({"role": "user", "content": "In Hangzhou"})

response = client.chat.completions.create(
  model="tongyi-intent-detect-v3",
  messages=messages
)

print("\nQuery: In Hangzhou")
print("Second-round output:\n")
print(response.choices[0].message.content)

Sample response

Query: I want to check the weather
First-round output:

<tags>
[weather inquiry]
</tags><tool_call>
[]
</tool_call><content>
OK. Which city's weather would you like to check?
</content>

Query: Hangzhou
Second-round output:

<tags>
[function call, json response]
</tags><tool_call>
[{"name": "get_current_weather", "arguments": {"location": "Hangzhou"}}]
</tool_call><content>

</content>
The first round returns a follow-up question in content and an empty tool_call. The second round completes the tool call.

FAQ

How many tools can I pass in?

Pass no more than 10 tools. Exceeding this limit can reduce tool call accuracy.

Why is the tool call returned as text instead of a tool_calls field?

tongyi-intent-detect-v3 returns intent and tool information inside the message content, wrapped in <tags>, <tool_call>, and <content> tags. Parse the tags with a regular expression as shown above rather than reading choices[0].message.tool_calls.

Function calling

Define tools and let general-purpose models call them.

Text generation models

Compare text generation models and their capabilities.
Intent understanding - QwenCloud