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
