---
title: Alibaba
description: Learn how to use Alibaba Cloud Model Studio (Qwen) models with the AI SDK.
url: "https://ai-sdk.dev/v5/providers/ai-sdk-providers/alibaba"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

[Alibaba Cloud Model Studio](https://modelstudio.console.alibabacloud.com/) provides access to the Qwen model series, including advanced reasoning capabilities.

API keys can be obtained from the [Console](https://modelstudio.console.alibabacloud.com/).

## Setup

The Alibaba provider is available via the `@ai-sdk/alibaba` module. You can install it with:

#### pnpm

```
pnpm add @ai-sdk/alibaba
```

#### npm

```
npm install @ai-sdk/alibaba
```

#### yarn

```
yarn add @ai-sdk/alibaba
```

#### bun

```
bun add @ai-sdk/alibaba
```

## Provider Instance

You can import the default provider instance `alibaba` from `@ai-sdk/alibaba`:

```ts
import { alibaba } from '@ai-sdk/alibaba';
```

For custom configuration, you can import `createAlibaba` and create a provider instance with your settings:

```ts
import { createAlibaba } from '@ai-sdk/alibaba';

const alibaba = createAlibaba({
  apiKey: process.env.ALIBABA_API_KEY ?? '',
});
```

You can use the following optional settings to customize the Alibaba provider instance:

- **baseURL** *string*

  Use a different URL prefix for API calls, e.g. to use proxy servers or regional endpoints.
  The default prefix is `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`.

- **embeddingBaseURL** *string*

  Use a different URL prefix for embedding API calls. The embedding API uses the DashScope
  native endpoint (not the OpenAI-compatible endpoint).
  The default prefix is `https://dashscope-intl.aliyuncs.com/api/v1`.

- **apiKey** *string*

  API key that is being sent using the `Authorization` header. It defaults to
  the `ALIBABA_API_KEY` environment variable.

- **headers** *Record\<string,string>*

  Custom headers to include in the requests.

- **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\<Response>*

  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.

- **includeUsage** *boolean*

  Include usage information in streaming responses. When enabled, token usage will be included in the final chunk.
  Defaults to `true`.

## Language Models

You can create language models using a provider instance:

```ts
import { alibaba } from '@ai-sdk/alibaba';
import { generateText } from 'ai';

const { text } = await generateText({
  model: alibaba('qwen-plus'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});
```

You can also use the `.chatModel()` or `.languageModel()` factory methods:

```ts
const model = alibaba.chatModel('qwen-plus');
// or
const model = alibaba.languageModel('qwen-plus');
```

Alibaba language models can be used in the `streamText` function
(see [AI SDK Core](/v5/docs/ai-sdk-core)).

The following optional provider options are available for Alibaba models:

- **enableThinking** *boolean*

  Enable thinking/reasoning mode for supported models. When enabled, the model generates reasoning content before the response.
  Defaults to `false`.

- **thinkingBudget** *number*

  Maximum number of reasoning tokens to generate. Limits the length of thinking content.

- **preserveThinking** *boolean*

  Preserve reasoning from previous assistant messages for supported models.
  When enabled, reasoning is sent separately as Alibaba `reasoning_content` and
  `preserve_thinking` is enabled. Defaults to `true` for models that support
  preserved thinking; set to `false` to opt out. Append AI SDK `responseMessages`
  unchanged when continuing the conversation. See Alibaba's
  [preserved-thinking documentation](https://docs.qwencloud.com/developer-guides/text-generation/thinking#preserve-thinking-in-multi-turn)
  for the list of supported models.

- **parallelToolCalls** *boolean*

  Whether to enable parallel function calling during tool use.
  Defaults to `true`.

### Thinking Mode

Alibaba's Qwen models support thinking/reasoning mode for complex problem-solving:

```ts
import { alibaba } from '@ai-sdk/alibaba';
import { generateText } from 'ai';

const { text, reasoning } = await generateText({
  model: alibaba('qwen3-max'),
  providerOptions: {
    alibaba: {
      enableThinking: true,
      thinkingBudget: 2048,
    },
  },
  prompt: 'How many "r"s are in the word "strawberry"?',
});

console.log('Reasoning:', reasoning);
console.log('Answer:', text);
```

For models that are thinking-only (like `qwen3-235b-a22b-thinking-2507`), thinking mode is enabled by default.

### Preserved Thinking in Multi-Turn Conversations

For models that support preserved thinking, the AI SDK replays reasoning from
previous assistant messages as Alibaba `reasoning_content` by default, so the
model can build on its earlier thought process:

```ts
import { alibaba, type AlibabaLanguageModelChatOptions } from '@ai-sdk/alibaba';
import { generateText, type ModelMessage } from 'ai';

const providerOptions = {
  alibaba: {
    enableThinking: true,
    thinkingBudget: 2048,
  } satisfies AlibabaLanguageModelChatOptions,
};

const opening: ModelMessage = {
  role: 'user',
  content: 'Is Kafka or RocketMQ a better fit for transactional messages?',
};

const first = await generateText({
  model: alibaba('qwen3.7-max'),
  messages: [opening],
  providerOptions,
});

const second = await generateText({
  model: alibaba('qwen3.7-max'),
  messages: [
    opening,
    ...first.responseMessages, // append unchanged to keep the reasoning parts
    { role: 'user', content: 'Which tradeoff mattered most?' },
  ],
  providerOptions,
});
```

When continuing the conversation, append `responseMessages` unchanged. If you
rebuild assistant history from visible text only, the reasoning parts are
discarded before the provider can serialize them as `reasoning_content`. Set
`preserveThinking: false` to opt out of replay, and note the following caveats:

- `preserveThinking` does not enable thinking by itself. Pair it with
  `enableThinking`/`thinkingBudget` or the top-level `reasoning` option.
- It is enabled by default only for models that Alibaba documents as supporting
  preserved thinking; for other models, `preserve_thinking` is not sent unless
  you set the option explicitly. See Alibaba's
  [preserved-thinking documentation](https://docs.qwencloud.com/developer-guides/text-generation/thinking#preserve-thinking-in-multi-turn)
  for the current list of supported models.
- Reasoning from the current tool-call round (after the last user message) is
  always sent back with tool results, as Alibaba recommends; the option only
  controls reasoning from earlier rounds.
- Preserved reasoning increases input token usage and billing.
- Historical reasoning remains separate from visible assistant text; it is never
  merged into `content`.

### Tool Calling

Alibaba models support tool calling with parallel execution:

```ts
import { alibaba } from '@ai-sdk/alibaba';
import { generateText, tool } from 'ai';
import { z } from 'zod';

const { text } = await generateText({
  model: alibaba('qwen-plus'),
  tools: {
    weather: tool({
      description: 'Get the weather in a location',
      parameters: z.object({
        location: z.string().describe('The location to get the weather for'),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72 + Math.floor(Math.random() * 21) - 10,
      }),
    }),
  },
  prompt: 'What is the weather in San Francisco?',
});
```

### Prompt Caching

Alibaba supports both implicit and explicit prompt caching to reduce costs for repeated prompts.

**Implicit caching** works automatically - the provider caches appropriate content without any configuration. For more control, you can use **explicit caching** by marking specific messages with `cache_control`:

### Single message cache control

```ts
import { alibaba } from '@ai-sdk/alibaba';
import { generateText } from 'ai';

const { text, usage } = await generateText({
  model: alibaba('qwen-plus'),
  messages: [
    {
      role: 'system',
      content: 'You are a helpful assistant. [... long system prompt ...]',
      providerOptions: {
        alibaba: {
          cache_control: { type: 'ephemeral' },
        },
      },
    },
  ],
});
```

### Multi-part message cache control

```ts
import { alibaba } from '@ai-sdk/alibaba';
import { generateText } from 'ai';

const longDocument = '... large document content ...';

const { text, usage } = await generateText({
  model: alibaba('qwen-plus'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Context: Please analyze this document.',
        },
        {
          type: 'text',
          text: longDocument,
          providerOptions: {
            alibaba: {
              cacheControl: { type: 'ephemeral' },
            },
          },
        },
      ],
    },
  ],
});
```

**Note:** The minimum content length for a cache block is 1,024 tokens.

## Embedding Models

You can create text embedding models using the `.textEmbeddingModel()` factory method.
For more on embeddings with the AI SDK see [`embed()`](/v5/docs/reference/ai-sdk-core/embed)
and [`embedMany()`](/v5/docs/reference/ai-sdk-core/embed-many).

```ts
const model = alibaba.textEmbeddingModel('text-embedding-v4');
```

You can use Alibaba embedding models to generate embeddings with the `embed` function:

```ts
import { alibaba, type AlibabaEmbeddingModelOptions } from '@ai-sdk/alibaba';
import { embed } from 'ai';

const { embedding, usage } = await embed({
  model: alibaba.textEmbeddingModel('text-embedding-v4'),
  value: 'sunny day at the beach',
  providerOptions: {
    alibaba: {
      textType: 'document',
      dimension: 1024,
      outputType: 'dense',
    } satisfies AlibabaEmbeddingModelOptions,
  },
});
```

Use `embedMany` to embed multiple text values. Alibaba text embedding models support
up to 10 values per API call; larger batches are split automatically by `embedMany`.

```ts
import { alibaba, type AlibabaEmbeddingModelOptions } from '@ai-sdk/alibaba';
import { embedMany } from 'ai';

const { embeddings } = await embedMany({
  model: alibaba.textEmbeddingModel('text-embedding-v4'),
  values: [
    'sunny day at the beach',
    'rainy afternoon in the city',
    'snowy night in the mountains',
  ],
  providerOptions: {
    alibaba: {
      textType: 'document',
      dimension: 1024,
    } satisfies AlibabaEmbeddingModelOptions,
  },
});
```

Alibaba embedding models support additional provider options that can be passed via
`providerOptions.alibaba`:

- **textType** *'query' | 'document'*

  Differentiates query text from document text for asymmetric retrieval tasks.
  Defaults to `document`.

- **dimension** *number*

  The dimension of the output embedding vectors. Defaults to 1024.
  `text-embedding-v4` also supports 1536 and 2048 dimensions.

- **outputType** *'dense' | 'sparse' | 'dense\&sparse'*

  Specifies the output vector type. Defaults to `dense`.
  The AI SDK embedding interface returns dense `number[]` vectors, so sparse-only
  output is not supported and will throw. Use `dense&sparse` to receive dense
  embeddings in `embedding`/`embeddings` and sparse vectors in
  `providerMetadata.alibaba.sparseEmbeddings`.

### Embedding Model Capabilities

| Model               | Default Dimensions | Flexible Dimensions                      | Max Values per Call |
| ------------------- | ------------------ | ---------------------------------------- | ------------------- |
| `text-embedding-v4` | 1024               | 64, 128, 256, 512, 768, 1024, 1536, 2048 | 10                  |
| `text-embedding-v3` | 1024               | 512, 768, 1024                           | 10                  |

The tables above list currently documented Alibaba text embedding models. You
can also pass any available provider model ID as a string if needed.

## Model Capabilities

Please see the [Alibaba Cloud Model Studio docs](https://www.alibabacloud.com/help/en/model-studio/models) for a full
list of available models. You can also pass any available provider model ID as
a string if needed.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)