Documentation Index
Fetch the complete documentation index at: https://mintlify.com/alibaba/zvec/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Qwen provides both dense and sparse text embedding capabilities using Alibaba Cloud’s DashScope service. Both classes support configurable dimensions and automatic result caching.
Location: python/zvec/extension/qwen_embedding_function.py
Installation
QwenDenseEmbedding
Dense text embedding function using Qwen (DashScope) API.
Constructor
from zvec.extension import QwenDenseEmbedding
QwenDenseEmbedding(
dimension: int,
model: str = "text-embedding-v4",
api_key: Optional[str] = None,
**kwargs
)
Parameters
Desired output embedding dimension. Common values:
512: Balanced performance and accuracy1024: Higher accuracy, larger storage1536: Maximum accuracy for supported models
model
str
default:"text-embedding-v4"
DashScope embedding model identifier. Options:
text-embedding-v4 (recommended)text-embedding-v3text-embedding-v2text-embedding-v1
api_key
Optional[str]
default:"None"
Methods
embed()
@lru_cache(maxsize=10)
def embed(self, input: TEXT) -> DenseVectorType:
"""Generate dense embedding vector for the input text."""
input (str): Input text string to embed. Maximum length depends on model (typically 2048-8192 tokens).
Returns:
DenseVectorType: List of floats representing the embedding vector. Length equals self.dimension.
Raises:
TypeError: If input is not a stringValueError: If input is empty or API returns errorRuntimeError: If network or DashScope service errors occur
Usage Examples
Basic Usage
from zvec.extension import QwenDenseEmbedding
import os
os.environ["DASHSCOPE_API_KEY"] = "your-api-key"
emb_func = QwenDenseEmbedding(dimension=1024)
vector = emb_func.embed("Hello, world!")
print(len(vector)) # 1024
Specific Model
emb_func = QwenDenseEmbedding(
dimension=512,
model="text-embedding-v3",
api_key="sk-xxxxx"
)
vector = emb_func.embed("Machine learning is fascinating")
print(isinstance(vector, list)) # True
Asymmetric Retrieval
# For search queries
query_emb = QwenDenseEmbedding(
dimension=1024,
text_type="query"
)
query_vector = query_emb.embed("What is machine learning?")
# For document embeddings
doc_emb = QwenDenseEmbedding(
dimension=1024,
text_type="document"
)
doc_vector = doc_emb.embed(
"Machine learning is a subset of artificial intelligence..."
)
QwenSparseEmbedding
Sparse text embedding function using Qwen (DashScope) API. Generates sparse keyword-weighted vectors suitable for lexical matching and BM25-style retrieval.
Constructor
from zvec.extension import QwenSparseEmbedding
QwenSparseEmbedding(
dimension: int,
model: str = "text-embedding-v4",
api_key: Optional[str] = None,
**kwargs
)
Parameters
Desired output embedding dimension. Common values:
512: Balanced performance1024: Higher accuracy1536: Maximum accuracy
model
str
default:"text-embedding-v4"
DashScope embedding model identifier.
api_key
Optional[str]
default:"None"
DashScope API key or None to use environment variable.
Additional DashScope API parameters:
encoding_type (Literal[“query”, “document”]): Encoding type
"query": Optimize for search queries (default)"document": Optimize for indexed documents
Methods
embed()
@lru_cache(maxsize=10)
def embed(self, input: TEXT) -> SparseVectorType:
"""Generate sparse embedding vector for the input text."""
input (str): Input text string to embed.
Returns:
SparseVectorType: Dictionary mapping dimension index to weight. Only non-zero dimensions included. Sorted by indices for consistency.
Raises:
TypeError: If input is not a stringValueError: If input is empty or API returns errorRuntimeError: If network or service errors occur
Usage Examples
Basic Usage
from zvec.extension import QwenSparseEmbedding
import os
os.environ["DASHSCOPE_API_KEY"] = "your-api-key"
query_emb = QwenSparseEmbedding(
dimension=1024,
encoding_type="query"
)
query_vec = query_emb.embed("machine learning")
print(type(query_vec)) # <class 'dict'>
print(len(query_vec)) # ~150-200 non-zero dimensions
Document Embedding
doc_emb = QwenSparseEmbedding(
dimension=1024,
encoding_type="document"
)
doc_vec = doc_emb.embed("Machine learning is a subset of AI")
print(isinstance(doc_vec, dict)) # True
Asymmetric Retrieval
# Query encoder
query_emb = QwenSparseEmbedding(
dimension=1024,
encoding_type="query"
)
# Document encoder
doc_emb = QwenSparseEmbedding(
dimension=1024,
encoding_type="document"
)
query_vec = query_emb.embed("what causes aging fast")
doc_vec = doc_emb.embed(
"UV-A light causes tanning, skin aging, and cataracts..."
)
# Calculate similarity (dot product)
similarity = sum(
query_vec.get(k, 0) * doc_vec.get(k, 0)
for k in set(query_vec) | set(doc_vec)
)
print(f"Similarity: {similarity}")
Inspecting Sparse Dimensions
query_vec = query_emb.embed("machine learning")
# Output is sorted by indices
print(list(query_vec.items())[:5])
# [(10, 0.45), (23, 0.87), (56, 0.32), (89, 1.12), (120, 0.65)]
# Sort by weight to find top terms
top_terms = sorted(query_vec.items(), key=lambda x: x[1], reverse=True)[:5]
for idx, weight in top_terms:
print(f"Dimension {idx}: {weight:.3f}")
Hybrid Retrieval
Combine dense and sparse embeddings for optimal search:
from zvec.extension import QwenDenseEmbedding, QwenSparseEmbedding
import os
os.environ["DASHSCOPE_API_KEY"] = "your-api-key"
# Dense for semantic similarity
dense_emb = QwenDenseEmbedding(dimension=1024)
# Sparse for lexical matching
sparse_emb = QwenSparseEmbedding(dimension=1024)
query = "deep learning neural networks"
# Get both embeddings
dense_vec = dense_emb.embed(query) # [0.1, -0.3, 0.5, ...]
sparse_vec = sparse_emb.embed(query) # {12: 0.8, 45: 1.2, ...}
# Combine scores for hybrid retrieval
# score = α * dense_score + (1-α) * sparse_score
Best Practices
Environment Variables: Store API keys securely:export DASHSCOPE_API_KEY="your-api-key"
emb_func = QwenDenseEmbedding(dimension=1024) # Auto-reads from env
Asymmetric Search: Use text_type="query" for queries and text_type="document" for documents to optimize retrieval accuracy.
Comparison: Dense vs Sparse
| Feature | QwenDenseEmbedding | QwenSparseEmbedding |
|---|
| Output Format | List of floats | Dictionary (sparse) |
| Typical Size | 512-1536 dimensions (all) | ~150-200 non-zero dimensions |
| Best For | Semantic similarity | Keyword matching |
| Memory | Fixed size | Variable, efficient |
| Interpretability | Low | High (terms visible) |
| Use Case | General retrieval | Lexical search, hybrid |
Error Handling
try:
vector = emb_func.embed("") # Empty string
except ValueError as e:
print(f"Error: {e}")
# Error: Input text cannot be empty or whitespace only
try:
vector = emb_func.embed(123) # Wrong type
except TypeError as e:
print(f"Error: {e}")
# Error: Expected 'input' to be str, got int
Notes
- Requires Python 3.10, 3.11, or 3.12
- Requires
dashscope package: pip install dashscope
- Results are cached (LRU cache, maxsize=10)
- Network connectivity required
- API costs may apply
- Sparse vectors are sorted by indices for consistency
See Also
