Use text-embedding-v4 for plain text or code. It supports advanced features such as instructions and sparse vectors, and covers most text processing scenarios.
100+ major languages, including Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian
1 million tokens (Validity: 90 days after activating Qwen Cloud)
text-embedding-v3
1,024 (default), 768, 512
10
8,192
$0.07
50+ major languages, including Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian
1 million tokens (Validity: 90 days after activating Qwen Cloud)
Batch size is the maximum number of texts that can be processed in a single API call. For example, the batch size for text-embedding-v4 is 10. This means you can pass up to 10 texts for embedding in a single request, and each text must not exceed 8,192 tokens. This limit applies to:
String array input: The array can contain a maximum of 10 elements.
File input: The text file can contain a maximum of 10 lines of text.
text-embedding-v4 and text-embedding-v3 support custom embedding dimensions. Higher dimensions retain richer semantic information but also increase storage and computation costs.
General scenarios (Recommended): 1024 dimensions offer the best balance between performance and cost, suitable for most semantic retrieval tasks.
High-precision scenarios: For domains requiring high precision, choose 1536 or 2048 dimensions. This provides a certain level of precision improvement but significantly increases storage and computation overhead.
Resource-constrained scenarios: In cost-sensitive scenarios, choose 768 or lower dimensions. This significantly reduces resource consumption but results in some loss of semantic information.
OpenAI compatible API
DashScope
Copy
import osfrom openai import OpenAIclient = OpenAI( api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",)resp = client.embeddings.create( model="text-embedding-v4", input=["I like it and will buy from here again"], # Set the embedding dimensions to 256 dimensions=256)print(f"Embedding dimensions: {len(resp.data[0].embedding)}")
Copy
import dashscopedashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'resp = dashscope.TextEmbedding.call( model="text-embedding-v4", input=["I like it and will buy from here again"], # Set the embedding dimensions to 256 dimension=256)print(f"Embedding dimensions: {len(resp.output['embeddings'][0]['embedding'])}")
Distinguish between query and document text (text_type)
This parameter can currently only be enabled through the DashScope SDK and API.
To achieve the best results in search-related tasks, process different types of content with targeted embedding to fully leverage their respective roles. The text_type parameter is designed for this purpose:
text_type: 'query': Use for query text entered by the user. The model generates a "title-like" vector that is more directional and optimized for "asking" and "finding".
text_type: 'document' (default): Use for document text stored in the database. The model generates a "body-like" vector that contains more comprehensive information and is optimized for being retrieved.
When using short text to match long text, distinguish between query and document. For tasks where all texts have the same role, such as clustering or classification, you do not need to set this parameter.
Use instructions to improve performance (instruct)
This parameter can currently only be enabled through the DashScope SDK and API.
Provide clear English instructions to guide text-embedding-v4 to optimize vector quality for specific retrieval scenarios, effectively improving precision. When using this feature, set the text_type parameter to query.
Copy
# Scenario: When building document vectors for a search engine, you can add an instruction to optimize the vector quality for retrieval.resp = dashscope.TextEmbedding.call( model="text-embedding-v4", input="Research papers on machine learning", text_type="query", instruct="Given a research paper query, retrieve relevant research paper")
This parameter can currently only be enabled through the DashScope SDK and API.
text-embedding-v4 and text-embedding-v3 support three types of vector output to meet the needs of different retrieval strategies.
Vector type (output_type)
Core advantages
Main drawbacks
Typical application scenarios
dense
Deep semantic understanding. Can identify synonyms and context, leading to more relevant retrieval results.
Higher computational and storage costs. Cannot guarantee exact keyword matching.
Semantic search, AI chat, content recommendation.
sparse
High computational efficiency. Focuses on exact keyword matching and fast filtering.
Sacrifices semantic understanding. Cannot handle synonyms or context.
Log retrieval, product SKU search, precise information filtering.
dense&sparse
Combines semantics and keywords for the best search results. Generation cost is the same. The API call overhead is identical to the single-vector mode.
Large storage requirements. More complex system architecture and retrieval logic.
The following code is for demonstration purposes only. In a production environment, pre-compute embedding vectors and store them in a vector database. During retrieval, you only need to compute the query vector.
Automatically group similar texts by analyzing the distances between their vectors.
Copy
# scikit-learn is required: pip install scikit-learnimport dashscopeimport numpy as npfrom sklearn.cluster import KMeansdashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'def cluster_texts(texts, n_clusters=2): """Cluster a set of texts""" # 1. Get the vectors for all texts resp = dashscope.TextEmbedding.call( model="text-embedding-v4", input=texts, dimension=1024 ) embeddings = np.array([item['embedding'] for item in resp.output['embeddings']]) # 2. Use the KMeans algorithm for clustering kmeans = KMeans(n_clusters=n_clusters, random_state=0, n_init='auto').fit(embeddings) # 3. Organize and return the results clusters = {i: [] for i in range(n_clusters)} for i, label in enumerate(kmeans.labels_): clusters[label].append(texts[i]) return clusters# Example usagedocuments_to_cluster = [ "Mobile phone company A releases a new phone", "Search engine company B launches a new system", "World Cup final: Argentina vs. France", "China wins another gold medal at the Olympics", "A company releases its latest AI chip", "European Cup match report"]clusters = cluster_texts(documents_to_cluster, n_clusters=2)for cluster_id, docs in clusters.items(): print(f"--- Cluster {cluster_id} ---") for doc in docs: print(f"- {doc}")
Recognize and classify new categories without pre-labeled examples by calculating the vector similarity between the input text and predefined labels.
Copy
import dashscopeimport numpy as npdashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'def cosine_similarity(a, b): """Calculate cosine similarity""" return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))def classify_text_zero_shot(text, labels): """Perform zero-shot text classification""" # 1. Get the vectors for the input text and all labels resp = dashscope.TextEmbedding.call( model="text-embedding-v4", input=[text] + labels, dimension=1024 ) embeddings = resp.output['embeddings'] text_embedding = embeddings[0]['embedding'] label_embeddings = [emb['embedding'] for emb in embeddings[1:]] # 2. Calculate the similarity with each label scores = [cosine_similarity(text_embedding, label_emb) for label_emb in label_embeddings] # 3. Return the label with the highest similarity best_match_index = np.argmax(scores) return labels[best_match_index], scores[best_match_index]# Example usagetext_to_classify = "The fabric of this dress is comfortable and the style is nice"possible_labels = ["Digital Products", "Apparel & Accessories", "Food & Beverage", "Home & Living"]label, score = classify_text_zero_shot(text_to_classify, possible_labels)print(f"Input text: '{text_to_classify}'")print(f"Best matching category: '{label}' (Similarity: {score:.3f})")
Identify anomalous data that differs significantly from normal patterns by calculating the vector similarity between a text vector and the center of normal sample vectors.
The threshold in the example code is for demonstration purposes only. In real-world business scenarios, the specific similarity value varies depending on the data content and distribution. There is no fixed threshold. Calibrate this value based on your own dataset.
Copy
import dashscopeimport numpy as npdef cosine_similarity(a, b): """Calculate cosine similarity""" return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))def detect_anomaly(new_comment, normal_comments, threshold=0.6): # 1. Vectorize all normal comments and the new comment all_texts = normal_comments + [new_comment] resp = dashscope.TextEmbedding.call( model="text-embedding-v4", input=all_texts, dimension=1024 ) embeddings = [item['embedding'] for item in resp.output['embeddings']] # 2. Calculate the center vector (average value) of the normal comments normal_embeddings = np.array(embeddings[:-1]) normal_center_vector = np.mean(normal_embeddings, axis=0) # 3. Calculate the similarity between the new comment and the center vector new_comment_embedding = np.array(embeddings[-1]) similarity = cosine_similarity(new_comment_embedding, normal_center_vector) # 4. Determine if it is an anomaly is_anomaly = similarity < threshold return is_anomaly, similarity# Example usagenormal_user_comments = [ "Today's meeting was productive", "The project is progressing smoothly", "The new version will be released next week", "User feedback is positive"]test_comments = { "Normal comment": "The feature works as expected", "Anomaly - meaningless garbled text": "asdfghjkl zxcvbnm"}print("--- Anomaly Detection Example ---")for desc, comment in test_comments.items(): is_anomaly, score = detect_anomaly(comment, normal_user_comments) result = "Yes" if is_anomaly else "No" print(f"Comment: '{comment}'") print(f"Is anomaly: {result} (Similarity to normal samples: {score:.3f})\n")
MTEB: Massive Text Embedding Benchmark, a comprehensive evaluation of general-purpose capabilities for tasks such as classification, clustering, and retrieval.
CMTEB: Chinese Massive Text Embedding Benchmark, an evaluation specifically for Chinese text.
Scores range from 0 to 100. A higher value indicates better performance.