[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72XS3TZGA7CPT65EXAWA80T":3,"skill-same:01M72XS3TZGA7CPT65EXAWA80T":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M72XS3TZGA7CPT65EXAWA80T","embedding-strategies",null,"Select and optimize embedding models for semantic search and RAG applications. Use when choosing embedding models, implementing chunking strategies, or optimizing embedding quality for specific domains.","steph-frtech\u002Fclaude-code-up","steph-frtech","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F198466323?v=4","01M72XD213FVQA2QXRGTJFKHE1","01M72XD227AANJ993SQTNZB1CK",1,"MIT","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fmarketplaces\u002Fwshobson\u002Fplugins\u002Fllm-application-dev\u002Fskills\u002Fembedding-strategies\u002FSKILL.md",[],[],"2026-11-10 22:39:42",false,"---\nname: embedding-strategies\ndescription: Select and optimize embedding models for semantic search and RAG applications. Use when choosing embedding models, implementing chunking strategies, or optimizing embedding quality for specific domains.\n---\n\n# Embedding Strategies\n\nGuide to selecting and optimizing embedding models for vector search applications.\n\n## When to Use This Skill\n\n- Choosing embedding models for RAG\n- Optimizing chunking strategies\n- Fine-tuning embeddings for domains\n- Comparing embedding model performance\n- Reducing embedding dimensions\n- Handling multilingual content\n\n## Core Concepts\n\n### 1. Embedding Model Comparison (2026)\n\n| Model                      | Dimensions | Max Tokens | Best For                            |\n| -------------------------- | ---------- | ---------- | ----------------------------------- |\n| **voyage-3-large**         | 1024       | 32000      | Claude apps (Anthropic recommended) |\n| **voyage-3**               | 1024       | 32000      | Claude apps, cost-effective         |\n| **voyage-code-3**          | 1024       | 32000      | Code search                         |\n| **voyage-finance-2**       | 1024       | 32000      | Financial documents                 |\n| **voyage-law-2**           | 1024       | 32000      | Legal documents                     |\n| **text-embedding-3-large** | 3072       | 8191       | OpenAI apps, high accuracy          |\n| **text-embedding-3-small** | 1536       | 8191       | OpenAI apps, cost-effective         |\n| **bge-large-en-v1.5**      | 1024       | 512        | Open source, local deployment       |\n| **all-MiniLM-L6-v2**       | 384        | 256        | Fast, lightweight                   |\n| **multilingual-e5-large**  | 1024       | 512        | Multi-language                      |\n\n### 2. Embedding Pipeline\n\n```\nDocument → Chunking → Preprocessing → Embedding Model → Vector\n                ↓\n        [Overlap, Size]  [Clean, Normalize]  [API\u002FLocal]\n```\n\n## Templates\n\n### Template 1: Voyage AI Embeddings (Recommended for Claude)\n\n```python\nfrom langchain_voyageai import VoyageAIEmbeddings\nfrom typing import List\nimport os\n\n# Initialize Voyage AI embeddings (recommended by Anthropic for Claude)\nembeddings = VoyageAIEmbeddings(\n    model=\"voyage-3-large\",\n    voyage_api_key=os.environ.get(\"VOYAGE_API_KEY\")\n)\n\ndef get_embeddings(texts: List[str]) -> List[List[float]]:\n    \"\"\"Get embeddings from Voyage AI.\"\"\"\n    return embeddings.embed_documents(texts)\n\ndef get_query_embedding(query: str) -> List[float]:\n    \"\"\"Get single query embedding.\"\"\"\n    return embeddings.embed_query(query)\n\n# Specialized models for domains\ncode_embeddings = VoyageAIEmbeddings(model=\"voyage-code-3\")\nfinance_embeddings = VoyageAIEmbeddings(model=\"voyage-finance-2\")\nlegal_embeddings = VoyageAIEmbeddings(model=\"voyage-law-2\")\n```\n\n### Template 2: OpenAI Embeddings\n\n```python\nfrom openai import OpenAI\nfrom typing import List\nimport numpy as np\n\nclient = OpenAI()\n\ndef get_embeddings(\n    texts: List[str],\n    model: str = \"text-embedding-3-small\",\n    dimensions: int = None\n) -> List[List[float]]:\n    \"\"\"Get embeddings from OpenAI with optional dimension reduction.\"\"\"\n    # Handle batching for large lists\n    batch_size = 100\n    all_embeddings = []\n\n    for i in range(0, len(texts), batch_size):\n        batch = texts[i:i + batch_size]\n\n        kwargs = {\"input\": batch, \"model\": model}\n        if dimensions:\n            # Matryoshka dimensionality reduction\n            kwargs[\"dimensions\"] = dimensions\n\n        response = client.embeddings.create(**kwargs)\n        embeddings = [item.embedding for item in response.data]\n        all_embeddings.extend(embeddings)\n\n    return all_embeddings\n\n\ndef get_embedding(text: str, **kwargs) -> List[float]:\n    \"\"\"Get single embedding.\"\"\"\n    return get_embeddings([text], **kwargs)[0]\n\n\n# Dimension reduction with Matryoshka embeddings\ndef get_reduced_embedding(text: str, dimensions: int = 512) -> List[float]:\n    \"\"\"Get embedding with reduced dimensions (Matryoshka).\"\"\"\n    return get_embedding(\n        text,\n        model=\"text-embedding-3-small\",\n        dimensions=dimensions\n    )\n```\n\n### Template 3: Local Embeddings with Sentence Transformers\n\n```python\nfrom sentence_transformers import SentenceTransformer\nfrom typing import List, Optional\nimport numpy as np\n\nclass LocalEmbedder:\n    \"\"\"Local embedding with sentence-transformers.\"\"\"\n\n    def __init__(\n        self,\n        model_name: str = \"BAAI\u002Fbge-large-en-v1.5\",\n        device: str = \"cuda\"\n    ):\n        self.model = SentenceTransformer(model_name, device=device)\n        self.model_name = model_name\n\n    def embed(\n        self,\n        texts: List[str],\n        normalize: bool = True,\n        show_progress: bool = False\n    ) -> np.ndarray:\n        \"\"\"Embed texts with optional normalization.\"\"\"\n        embeddings = self.model.encode(\n            texts,\n            normalize_embeddings=normalize,\n            show_progress_bar=show_progress,\n            convert_to_numpy=True\n        )\n        return embeddings\n\n    def embed_query(self, query: str) -> np.ndarray:\n        \"\"\"Embed a query with appropriate prefix for retrieval models.\"\"\"\n        # BGE and similar models benefit from query prefix\n        if \"bge\" in self.model_name.lower():\n            query = f\"Represent this sentence for searching relevant passages: {query}\"\n        return self.embed([query])[0]\n\n    def embed_documents(self, documents: List[str]) -> np.ndarray:\n        \"\"\"Embed documents for indexing.\"\"\"\n        return self.embed(documents)\n\n\n# E5 model with instructions\nclass E5Embedder:\n    def __init__(self, model_name: str = \"intfloat\u002Fmultilingual-e5-large\"):\n        self.model = SentenceTransformer(model_name)\n\n    def embed_query(self, query: str) -> np.ndarray:\n        \"\"\"E5 requires 'query:' prefix for queries.\"\"\"\n        return self.model.encode(f\"query: {query}\")\n\n    def embed_document(self, document: str) -> np.ndarray:\n        \"\"\"E5 requires 'passage:' prefix for documents.\"\"\"\n        return self.model.encode(f\"passage: {document}\")\n```\n\n### Template 4: Chunking Strategies\n\n```python\nfrom typing import List, Tuple\nimport re\n\ndef chunk_by_tokens(\n    text: str,\n    chunk_size: int = 512,\n    chunk_overlap: int = 50,\n    tokenizer=None\n) -> List[str]:\n    \"\"\"Chunk text by token count.\"\"\"\n    import tiktoken\n    tokenizer = tokenizer or tiktoken.get_encoding(\"cl100k_base\")\n\n    tokens = tokenizer.encode(text)\n    chunks = []\n\n    start = 0\n    while start \u003C len(tokens):\n        end = start + chunk_size\n        chunk_tokens = tokens[start:end]\n        chunk_text = tokenizer.decode(chunk_tokens)\n        chunks.append(chunk_text)\n        start = end - chunk_overlap\n\n    return chunks\n\n\ndef chunk_by_sentences(\n    text: str,\n    max_chunk_size: int = 1000,\n    min_chunk_size: int = 100\n) -> List[str]:\n    \"\"\"Chunk text by sentences, respecting size limits.\"\"\"\n    import nltk\n    sentences = nltk.sent_tokenize(text)\n\n    chunks = []\n    current_chunk = []\n    current_size = 0\n\n    for sentence in sentences:\n        sentence_size = len(sentence)\n\n        if current_size + sentence_size > max_chunk_size and current_chunk:\n            chunks.append(\" \".join(current_chunk))\n            current_chunk = []\n            current_size = 0\n\n        current_chunk.append(sentence)\n        current_size += sentence_size\n\n    if current_chunk:\n        chunks.append(\" \".join(current_chunk))\n\n    return chunks\n\n\ndef chunk_by_semantic_sections(\n    text: str,\n    headers_pattern: str = r'^#{1,3}\\s+.+$'\n) -> List[Tuple[str, str]]:\n    \"\"\"Chunk markdown by headers, preserving hierarchy.\"\"\"\n    lines = text.split('\\n')\n    chunks = []\n    current_header = \"\"\n    current_content = []\n\n    for line in lines:\n        if re.match(headers_pattern, line, re.MULTILINE):\n            if current_content:\n                chunks.append((current_header, '\\n'.join(current_content)))\n            current_header = line\n            current_content = []\n        else:\n            current_content.append(line)\n\n    if current_content:\n        chunks.append((current_header, '\\n'.join(current_content)))\n\n    return chunks\n\n\ndef recursive_character_splitter(\n    text: str,\n    chunk_size: int = 1000,\n    chunk_overlap: int = 200,\n    separators: List[str] = None\n) -> List[str]:\n    \"\"\"LangChain-style recursive splitter.\"\"\"\n    separators = separators or [\"\\n\\n\", \"\\n\", \". \", \" \", \"\"]\n\n    def split_text(text: str, separators: List[str]) -> List[str]:\n        if not text:\n            return []\n\n        separator = separators[0]\n        remaining_separators = separators[1:]\n\n        if separator == \"\":\n            # Character-level split\n            return [text[i:i+chunk_size] for i in range(0, len(text), chunk_size - chunk_overlap)]\n\n        splits = text.split(separator)\n        chunks = []\n        current_chunk = []\n        current_length = 0\n\n        for split in splits:\n            split_length = len(split) + len(separator)\n\n            if current_length + split_length > chunk_size and current_chunk:\n                chunk_text = separator.join(current_chunk)\n\n                # Recursively split if still too large\n                if len(chunk_text) > chunk_size and remaining_separators:\n                    chunks.extend(split_text(chunk_text, remaining_separators))\n                else:\n                    chunks.append(chunk_text)\n\n                # Start new chunk with overlap\n                overlap_splits = []\n                overlap_length = 0\n                for s in reversed(current_chunk):\n                    if overlap_length + len(s) \u003C= chunk_overlap:\n                        overlap_splits.insert(0, s)\n                        overlap_length += len(s)\n                    else:\n                        break\n                current_chunk = overlap_splits\n                current_length = overlap_length\n\n            current_chunk.append(split)\n            current_length += split_length\n\n        if current_chunk:\n            chunks.append(separator.join(current_chunk))\n\n        return chunks\n\n    return split_text(text, separators)\n```\n\n### Template 5: Domain-Specific Embedding Pipeline\n\n```python\nimport re\nfrom typing import List, Optional\nfrom dataclasses import dataclass\n\n@dataclass\nclass EmbeddedDocument:\n    id: str\n    document_id: str\n    chunk_index: int\n    text: str\n    embedding: List[float]\n    metadata: dict\n\nclass DomainEmbeddingPipeline:\n    \"\"\"Pipeline for domain-specific embeddings.\"\"\"\n\n    def __init__(\n        self,\n        embedding_model: str = \"voyage-3-large\",\n        chunk_size: int = 512,\n        chunk_overlap: int = 50,\n        preprocessing_fn=None\n    ):\n        self.embeddings = VoyageAIEmbeddings(model=embedding_model)\n        self.chunk_size = chunk_size\n        self.chunk_overlap = chunk_overlap\n        self.preprocess = preprocessing_fn or self._default_preprocess\n\n    def _default_preprocess(self, text: str) -> str:\n        \"\"\"Default preprocessing.\"\"\"\n        # Remove excessive whitespace\n        text = re.sub(r'\\s+', ' ', text)\n        # Remove special characters (customize for your domain)\n        text = re.sub(r'[^\\w\\s.,!?-]', '', text)\n        return text.strip()\n\n    async def process_documents(\n        self,\n        documents: List[dict],\n        id_field: str = \"id\",\n        content_field: str = \"content\",\n        metadata_fields: Optional[List[str]] = None\n    ) -> List[EmbeddedDocument]:\n        \"\"\"Process documents for vector storage.\"\"\"\n        processed = []\n\n        for doc in documents:\n            content = doc[content_field]\n            doc_id = doc[id_field]\n\n            # Preprocess\n            cleaned = self.preprocess(content)\n\n            # Chunk\n            chunks = chunk_by_tokens(\n                cleaned,\n                self.chunk_size,\n                self.chunk_overlap\n            )\n\n            # Create embeddings\n            embeddings = await self.embeddings.aembed_documents(chunks)\n\n            # Create records\n            for i, (chunk, embedding) in enumerate(zip(chunks, embeddings)):\n                metadata = {\"document_id\": doc_id, \"chunk_index\": i}\n\n                # Add specified metadata fields\n                if metadata_fields:\n                    for field in metadata_fields:\n                        if field in doc:\n                            metadata[field] = doc[field]\n\n                processed.append(EmbeddedDocument(\n                    id=f\"{doc_id}_chunk_{i}\",\n                    document_id=doc_id,\n                    chunk_index=i,\n                    text=chunk,\n                    embedding=embedding,\n                    metadata=metadata\n                ))\n\n        return processed\n\n\n# Code-specific pipeline\nclass CodeEmbeddingPipeline:\n    \"\"\"Specialized pipeline for code embeddings.\"\"\"\n\n    def __init__(self):\n        # Use Voyage's code-specific model\n        self.embeddings = VoyageAIEmbeddings(model=\"voyage-code-3\")\n\n    def chunk_code(self, code: str, language: str) -> List[dict]:\n        \"\"\"Chunk code by functions\u002Fclasses using tree-sitter.\"\"\"\n        try:\n            import tree_sitter_languages\n            parser = tree_sitter_languages.get_parser(language)\n            tree = parser.parse(bytes(code, \"utf8\"))\n\n            chunks = []\n            # Extract function and class definitions\n            self._extract_nodes(tree.root_node, code, chunks)\n            return chunks\n        except ImportError:\n            # Fallback to simple chunking\n            return [{\"text\": code, \"type\": \"module\"}]\n\n    def _extract_nodes(self, node, source_code: str, chunks: list):\n        \"\"\"Recursively extract function\u002Fclass definitions.\"\"\"\n        if node.type in ['function_definition', 'class_definition', 'method_definition']:\n            text = source_code[node.start_byte:node.end_byte]\n            chunks.append({\n                \"text\": text,\n                \"type\": node.type,\n                \"name\": self._get_name(node),\n                \"start_line\": node.start_point[0],\n                \"end_line\": node.end_point[0]\n            })\n        for child in node.children:\n            self._extract_nodes(child, source_code, chunks)\n\n    def _get_name(self, node) -> str:\n        \"\"\"Extract name from function\u002Fclass node.\"\"\"\n        for child in node.children:\n            if child.type == 'identifier' or child.type == 'name':\n                return child.text.decode('utf8')\n        return \"unknown\"\n\n    async def embed_with_context(\n        self,\n        chunk: str,\n        context: str = \"\"\n    ) -> List[float]:\n        \"\"\"Embed code with surrounding context.\"\"\"\n        if context:\n            combined = f\"Context: {context}\\n\\nCode:\\n{chunk}\"\n        else:\n            combined = chunk\n        return await self.embeddings.aembed_query(combined)\n```\n\n### Template 6: Embedding Quality Evaluation\n\n```python\nimport numpy as np\nfrom typing import List, Dict\n\ndef evaluate_retrieval_quality(\n    queries: List[str],\n    relevant_docs: List[List[str]],  # List of relevant doc IDs per query\n    retrieved_docs: List[List[str]],  # List of retrieved doc IDs per query\n    k: int = 10\n) -> Dict[str, float]:\n    \"\"\"Evaluate embedding quality for retrieval.\"\"\"\n\n    def precision_at_k(relevant: set, retrieved: List[str], k: int) -> float:\n        retrieved_k = retrieved[:k]\n        relevant_retrieved = len(set(retrieved_k) & relevant)\n        return relevant_retrieved \u002F k if k > 0 else 0\n\n    def recall_at_k(relevant: set, retrieved: List[str], k: int) -> float:\n        retrieved_k = retrieved[:k]\n        relevant_retrieved = len(set(retrieved_k) & relevant)\n        return relevant_retrieved \u002F len(relevant) if relevant else 0\n\n    def mrr(relevant: set, retrieved: List[str]) -> float:\n        for i, doc in enumerate(retrieved):\n            if doc in relevant:\n                return 1 \u002F (i + 1)\n        return 0\n\n    def ndcg_at_k(relevant: set, retrieved: List[str], k: int) -> float:\n        dcg = sum(\n            1 \u002F np.log2(i + 2) if doc in relevant else 0\n            for i, doc in enumerate(retrieved[:k])\n        )\n        ideal_dcg = sum(1 \u002F np.log2(i + 2) for i in range(min(len(relevant), k)))\n        return dcg \u002F ideal_dcg if ideal_dcg > 0 else 0\n\n    metrics = {\n        f\"precision@{k}\": [],\n        f\"recall@{k}\": [],\n        \"mrr\": [],\n        f\"ndcg@{k}\": []\n    }\n\n    for relevant, retrieved in zip(relevant_docs, retrieved_docs):\n        relevant_set = set(relevant)\n        metrics[f\"precision@{k}\"].append(precision_at_k(relevant_set, retrieved, k))\n        metrics[f\"recall@{k}\"].append(recall_at_k(relevant_set, retrieved, k))\n        metrics[\"mrr\"].append(mrr(relevant_set, retrieved))\n        metrics[f\"ndcg@{k}\"].append(ndcg_at_k(relevant_set, retrieved, k))\n\n    return {name: np.mean(values) for name, values in metrics.items()}\n\n\ndef compute_embedding_similarity(\n    embeddings1: np.ndarray,\n    embeddings2: np.ndarray,\n    metric: str = \"cosine\"\n) -> np.ndarray:\n    \"\"\"Compute similarity matrix between embedding sets.\"\"\"\n    if metric == \"cosine\":\n        # Normalize and compute dot product\n        norm1 = embeddings1 \u002F np.linalg.norm(embeddings1, axis=1, keepdims=True)\n        norm2 = embeddings2 \u002F np.linalg.norm(embeddings2, axis=1, keepdims=True)\n        return norm1 @ norm2.T\n    elif metric == \"euclidean\":\n        from scipy.spatial.distance import cdist\n        return -cdist(embeddings1, embeddings2, metric='euclidean')\n    elif metric == \"dot\":\n        return embeddings1 @ embeddings2.T\n    else:\n        raise ValueError(f\"Unknown metric: {metric}\")\n\n\ndef compare_embedding_models(\n    texts: List[str],\n    models: Dict[str, callable],\n    queries: List[str],\n    relevant_indices: List[List[int]],\n    k: int = 5\n) -> Dict[str, Dict[str, float]]:\n    \"\"\"Compare multiple embedding models on retrieval quality.\"\"\"\n    results = {}\n\n    for model_name, embed_fn in models.items():\n        # Embed all texts\n        doc_embeddings = np.array(embed_fn(texts))\n\n        retrieved_per_query = []\n        for query in queries:\n            query_embedding = np.array(embed_fn([query])[0])\n            # Compute similarities\n            similarities = compute_embedding_similarity(\n                query_embedding.reshape(1, -1),\n                doc_embeddings,\n                metric=\"cosine\"\n            )[0]\n            # Get top-k indices\n            top_k_indices = np.argsort(similarities)[::-1][:k]\n            retrieved_per_query.append([str(i) for i in top_k_indices])\n\n        # Convert relevant indices to string IDs\n        relevant_docs = [[str(i) for i in indices] for indices in relevant_indices]\n\n        results[model_name] = evaluate_retrieval_quality(\n            queries, relevant_docs, retrieved_per_query, k\n        )\n\n    return results\n```\n\n## Best Practices\n\n### Do's\n\n- **Match model to use case**: Code vs prose vs multilingual\n- **Chunk thoughtfully**: Preserve semantic boundaries\n- **Normalize embeddings**: For cosine similarity search\n- **Batch requests**: More efficient than one-by-one\n- **Cache embeddings**: Avoid recomputing for static content\n- **Use Voyage AI for Claude apps**: Recommended by Anthropic\n\n### Don'ts\n\n- **Don't ignore token limits**: Truncation loses information\n- **Don't mix embedding models**: Incompatible vector spaces\n- **Don't skip preprocessing**: Garbage in, garbage out\n- **Don't over-chunk**: Lose important context\n- **Don't forget metadata**: Essential for filtering and debugging\n","# Embedding Strategies\n\nGuide to selecting and optimizing embedding models for vector search applications.\n\n## When to Use This Skill\n\n- Choosing embedding models for RAG\n- Optimizing chunking strategies\n- Fine-tuning embeddings for domains\n- Comparing embedding model performance\n- Reducing embedding dimensions\n- Handling multilingual content\n\n## Core Concepts\n\n### 1. Embedding Model Comparison (2026)\n\n| Model                      | Dimensions | Max Tokens | Best For                            |\n| -------------------------- | ---------- | ---------- | ----------------------------------- |\n| **voyage-3-large**         | 1024       | 32000      | Claude apps (Anthropic recommended) |\n| **voyage-3**               | 1024       | 32000      | Claude apps, cost-effective         |\n| **voyage-code-3**          | 1024       | 32000      | Code search                         |\n| **voyage-finance-2**       | 1024       | 32000      | Financial documents                 |\n| **voyage-law-2**           | 1024       | 32000      | Legal documents                     |\n| **text-embedding-3-large** | 3072       | 8191       | OpenAI apps, high accuracy          |\n| **text-embedding-3-small** | 1536       | 8191       | OpenAI apps, cost-effective         |\n| **bge-large-en-v1.5**      | 1024       | 512        | Open source, local deployment       |\n| **all-MiniLM-L6-v2**       | 384        | 256        | Fast, lightweight                   |\n| **multilingual-e5-large**  | 1024       | 512        | Multi-language                      |\n\n### 2. Embedding Pipeline\n\n```\nDocument → Chunking → Preprocessing → Embedding Model → Vector\n                ↓\n        [Overlap, Size]  [Clean, Normalize]  [API\u002FLocal]\n```\n\n## Templates\n\n### Template 1: Voyage AI Embeddings (Recommended for Claude)\n\n```python\nfrom langchain_voyageai import VoyageAIEmbeddings\nfrom typing import List\nimport os\n\n# Initialize Voyage AI embeddings (recommended by Anthropic for Claude)\nembeddings = VoyageAIEmbeddings(\n    model=\"voyage-3-large\",\n    voyage_api_key=os.environ.get(\"VOYAGE_API_KEY\")\n)\n\ndef get_embeddings(texts: List[str]) -> List[List[float]]:\n    \"\"\"Get embeddings from Voyage AI.\"\"\"\n    return embeddings.embed_documents(texts)\n\ndef get_query_embedding(query: str) -> List[float]:\n    \"\"\"Get single query embedding.\"\"\"\n    return embeddings.embed_query(query)\n\n# Specialized models for domains\ncode_embeddings = VoyageAIEmbeddings(model=\"voyage-code-3\")\nfinance_embeddings = VoyageAIEmbeddings(model=\"voyage-finance-2\")\nlegal_embeddings = VoyageAIEmbeddings(model=\"voyage-law-2\")\n```\n\n### Template 2: OpenAI Embeddings\n\n```python\nfrom openai import OpenAI\nfrom typing import List\nimport numpy as np\n\nclient = OpenAI()\n\ndef get_embeddings(\n    texts: List[str],\n    model: str = \"text-embedding-3-small\",\n    dimensions: int = None\n) -> List[List[float]]:\n    \"\"\"Get embeddings from OpenAI with optional dimension reduction.\"\"\"\n    # Handle batching for large lists\n    batch_size = 100\n    all_embeddings = []\n\n    for i in range(0, len(texts), batch_size):\n        batch = texts[i:i + batch_size]\n\n        kwargs = {\"input\": batch, \"model\": model}\n        if dimensions:\n            # Matryoshka dimensionality reduction\n            kwargs[\"dimensions\"] = dimensions\n\n        response = client.embeddings.create(**kwargs)\n        embeddings = [item.embedding for item in response.data]\n        all_embeddings.extend(embeddings)\n\n    return all_embeddings\n\n\ndef get_embedding(text: str, **kwargs) -> List[float]:\n    \"\"\"Get single embedding.\"\"\"\n    return get_embeddings([text], **kwargs)[0]\n\n\n# Dimension reduction with Matryoshka embeddings\ndef get_reduced_embedding(text: str, dimensions: int = 512) -> List[float]:\n    \"\"\"Get embedding with reduced dimensions (Matryoshka).\"\"\"\n    return get_embedding(\n        text,\n        model=\"text-embedding-3-small\",\n        dimensions=dimensions\n    )\n```\n\n### Template 3: Local Embeddings with Sentence Transformers\n\n```python\nfrom sentence_transformers import SentenceTransformer\nfrom typing import List, Optional\nimport numpy as np\n\nclass LocalEmbedder:\n    \"\"\"Local embedding with sentence-transformers.\"\"\"\n\n    def __init__(\n        self,\n        model_name: str = \"BAAI\u002Fbge-large-en-v1.5\",\n        device: str = \"cuda\"\n    ):\n        self.model = SentenceTransformer(model_name, device=device)\n        self.model_name = model_name\n\n    def embed(\n        self,\n        texts: List[str],\n        normalize: bool = True,\n        show_progress: bool = False\n    ) -> np.ndarray:\n        \"\"\"Embed texts with optional normalization.\"\"\"\n        embeddings = self.model.encode(\n            texts,\n            normalize_embeddings=normalize,\n            show_progress_bar=show_progress,\n            convert_to_numpy=True\n        )\n        return embeddings\n\n    def embed_query(self, query: str) -> np.ndarray:\n        \"\"\"Embed a query with appropriate prefix for retrieval models.\"\"\"\n        # BGE and similar models benefit from query prefix\n        if \"bge\" in self.model_name.lower():\n            query = f\"Represent this sentence for searching relevant passages: {query}\"\n        return self.embed([query])[0]\n\n    def embed_documents(self, documents: List[str]) -> np.ndarray:\n        \"\"\"Embed documents for indexing.\"\"\"\n        return self.embed(documents)\n\n\n# E5 model with instructions\nclass E5Embedder:\n    def __init__(self, model_name: str = \"intfloat\u002Fmultilingual-e5-large\"):\n        self.model = SentenceTransformer(model_name)\n\n    def embed_query(self, query: str) -> np.ndarray:\n        \"\"\"E5 requires 'query:' prefix for queries.\"\"\"\n        return self.model.encode(f\"query: {query}\")\n\n    def embed_document(self, document: str) -> np.ndarray:\n        \"\"\"E5 requires 'passage:' prefix for documents.\"\"\"\n        return self.model.encode(f\"passage: {document}\")\n```\n\n### Template 4: Chunking Strategies\n\n```python\nfrom typing import List, Tuple\nimport re\n\ndef chunk_by_tokens(\n    text: str,\n    chunk_size: int = 512,\n    chunk_overlap: int = 50,\n    tokenizer=None\n) -> List[str]:\n    \"\"\"Chunk text by token count.\"\"\"\n    import tiktoken\n    tokenizer = tokenizer or tiktoken.get_encoding(\"cl100k_base\")\n\n    tokens = tokenizer.encode(text)\n    chunks = []\n\n    start = 0\n    while start \u003C len(tokens):\n        end = start + chunk_size\n        chunk_tokens = tokens[start:end]\n        chunk_text = tokenizer.decode(chunk_tokens)\n        chunks.append(chunk_text)\n        start = end - chunk_overlap\n\n    return chunks\n\n\ndef chunk_by_sentences(\n    text: str,\n    max_chunk_size: int = 1000,\n    min_chunk_size: int = 100\n) -> List[str]:\n    \"\"\"Chunk text by sentences, respecting size limits.\"\"\"\n    import nltk\n    sentences = nltk.sent_tokenize(text)\n\n    chunks = []\n    current_chunk = []\n    current_size = 0\n\n    for sentence in sentences:\n        sentence_size = len(sentence)\n\n        if current_size + sentence_size > max_chunk_size and current_chunk:\n            chunks.append(\" \".join(current_chunk))\n            current_chunk = []\n            current_size = 0\n\n        current_chunk.append(sentence)\n        current_size += sentence_size\n\n    if current_chunk:\n        chunks.append(\" \".join(current_chunk))\n\n    return chunks\n\n\ndef chunk_by_semantic_sections(\n    text: str,\n    headers_pattern: str = r'^#{1,3}\\s+.+$'\n) -> List[Tuple[str, str]]:\n    \"\"\"Chunk markdown by headers, preserving hierarchy.\"\"\"\n    lines = text.split('\\n')\n    chunks = []\n    current_header = \"\"\n    current_content = []\n\n    for line in lines:\n        if re.match(headers_pattern, line, re.MULTILINE):\n            if current_content:\n                chunks.append((current_header, '\\n'.join(current_content)))\n            current_header = line\n            current_content = []\n        else:\n            current_content.append(line)\n\n    if current_content:\n        chunks.append((current_header, '\\n'.join(current_content)))\n\n    return chunks\n\n\ndef recursive_character_splitter(\n    text: str,\n    chunk_size: int = 1000,\n    chunk_overlap: int = 200,\n    separators: List[str] = None\n) -> List[str]:\n    \"\"\"LangChain-style recursive splitter.\"\"\"\n    separators = separators or [\"\\n\\n\", \"\\n\", \". \", \" \", \"\"]\n\n    def split_text(text: str, separators: List[str]) -> List[str]:\n        if not text:\n            return []\n\n        separator = separators[0]\n        remaining_separators = separators[1:]\n\n        if separator == \"\":\n            # Character-level split\n            return [text[i:i+chunk_size] for i in range(0, len(text), chunk_size - chunk_overlap)]\n\n        splits = text.split(separator)\n        chunks = []\n        current_chunk = []\n        current_length = 0\n\n        for split in splits:\n            split_length = len(split) + len(separator)\n\n            if current_length + split_length > chunk_size and current_chunk:\n                chunk_text = separator.join(current_chunk)\n\n                # Recursively split if still too large\n                if len(chunk_text) > chunk_size and remaining_separators:\n                    chunks.extend(split_text(chunk_text, remaining_separators))\n                else:\n                    chunks.append(chunk_text)\n\n                # Start new chunk with overlap\n                overlap_splits = []\n                overlap_length = 0\n                for s in reversed(current_chunk):\n                    if overlap_length + len(s) \u003C= chunk_overlap:\n                        overlap_splits.insert(0, s)\n                        overlap_length += len(s)\n                    else:\n                        break\n                current_chunk = overlap_splits\n                current_length = overlap_length\n\n            current_chunk.append(split)\n            current_length += split_length\n\n        if current_chunk:\n            chunks.append(separator.join(current_chunk))\n\n        return chunks\n\n    return split_text(text, separators)\n```\n\n### Template 5: Domain-Specific Embedding Pipeline\n\n```python\nimport re\nfrom typing import List, Optional\nfrom dataclasses import dataclass\n\n@dataclass\nclass EmbeddedDocument:\n    id: str\n    document_id: str\n    chunk_index: int\n    text: str\n    embedding: List[float]\n    metadata: dict\n\nclass DomainEmbeddingPipeline:\n    \"\"\"Pipeline for domain-specific embeddings.\"\"\"\n\n    def __init__(\n        self,\n        embedding_model: str = \"voyage-3-large\",\n        chunk_size: int = 512,\n        chunk_overlap: int = 50,\n        preprocessing_fn=None\n    ):\n        self.embeddings = VoyageAIEmbeddings(model=embedding_model)\n        self.chunk_size = chunk_size\n        self.chunk_overlap = chunk_overlap\n        self.preprocess = preprocessing_fn or self._default_preprocess\n\n    def _default_preprocess(self, text: str) -> str:\n        \"\"\"Default preprocessing.\"\"\"\n        # Remove excessive whitespace\n        text = re.sub(r'\\s+', ' ', text)\n        # Remove special characters (customize for your domain)\n        text = re.sub(r'[^\\w\\s.,!?-]', '', text)\n        return text.strip()\n\n    async def process_documents(\n        self,\n        documents: List[dict],\n        id_field: str = \"id\",\n        content_field: str = \"content\",\n        metadata_fields: Optional[List[str]] = None\n    ) -> List[EmbeddedDocument]:\n        \"\"\"Process documents for vector storage.\"\"\"\n        processed = []\n\n        for doc in documents:\n            content = doc[content_field]\n            doc_id = doc[id_field]\n\n            # Preprocess\n            cleaned = self.preprocess(content)\n\n            # Chunk\n            chunks = chunk_by_tokens(\n                cleaned,\n                self.chunk_size,\n                self.chunk_overlap\n            )\n\n            # Create embeddings\n            embeddings = await self.embeddings.aembed_documents(chunks)\n\n            # Create records\n            for i, (chunk, embedding) in enumerate(zip(chunks, embeddings)):\n                metadata = {\"document_id\": doc_id, \"chunk_index\": i}\n\n                # Add specified metadata fields\n                if metadata_fields:\n                    for field in metadata_fields:\n                        if field in doc:\n                            metadata[field] = doc[field]\n\n                processed.append(EmbeddedDocument(\n                    id=f\"{doc_id}_chunk_{i}\",\n                    document_id=doc_id,\n                    chunk_index=i,\n                    text=chunk,\n                    embedding=embedding,\n                    metadata=metadata\n                ))\n\n        return processed\n\n\n# Code-specific pipeline\nclass CodeEmbeddingPipeline:\n    \"\"\"Specialized pipeline for code embeddings.\"\"\"\n\n    def __init__(self):\n        # Use Voyage's code-specific model\n        self.embeddings = VoyageAIEmbeddings(model=\"voyage-code-3\")\n\n    def chunk_code(self, code: str, language: str) -> List[dict]:\n        \"\"\"Chunk code by functions\u002Fclasses using tree-sitter.\"\"\"\n        try:\n            import tree_sitter_languages\n            parser = tree_sitter_languages.get_parser(language)\n            tree = parser.parse(bytes(code, \"utf8\"))\n\n            chunks = []\n            # Extract function and class definitions\n            self._extract_nodes(tree.root_node, code, chunks)\n            return chunks\n        except ImportError:\n            # Fallback to simple chunking\n            return [{\"text\": code, \"type\": \"module\"}]\n\n    def _extract_nodes(self, node, source_code: str, chunks: list):\n        \"\"\"Recursively extract function\u002Fclass definitions.\"\"\"\n        if node.type in ['function_definition', 'class_definition', 'method_definition']:\n            text = source_code[node.start_byte:node.end_byte]\n            chunks.append({\n                \"text\": text,\n                \"type\": node.type,\n                \"name\": self._get_name(node),\n                \"start_line\": node.start_point[0],\n                \"end_line\": node.end_point[0]\n            })\n        for child in node.children:\n            self._extract_nodes(child, source_code, chunks)\n\n    def _get_name(self, node) -> str:\n        \"\"\"Extract name from function\u002Fclass node.\"\"\"\n        for child in node.children:\n            if child.type == 'identifier' or child.type == 'name':\n                return child.text.decode('utf8')\n        return \"unknown\"\n\n    async def embed_with_context(\n        self,\n        chunk: str,\n        context: str = \"\"\n    ) -> List[float]:\n        \"\"\"Embed code with surrounding context.\"\"\"\n        if context:\n            combined = f\"Context: {context}\\n\\nCode:\\n{chunk}\"\n        else:\n            combined = chunk\n        return await self.embeddings.aembed_query(combined)\n```\n\n### Template 6: Embedding Quality Evaluation\n\n```python\nimport numpy as np\nfrom typing import List, Dict\n\ndef evaluate_retrieval_quality(\n    queries: List[str],\n    relevant_docs: List[List[str]],  # List of relevant doc IDs per query\n    retrieved_docs: List[List[str]],  # List of retrieved doc IDs per query\n    k: int = 10\n) -> Dict[str, float]:\n    \"\"\"Evaluate embedding quality for retrieval.\"\"\"\n\n    def precision_at_k(relevant: set, retrieved: List[str], k: int) -> float:\n        retrieved_k = retrieved[:k]\n        relevant_retrieved = len(set(retrieved_k) & relevant)\n        return relevant_retrieved \u002F k if k > 0 else 0\n\n    def recall_at_k(relevant: set, retrieved: List[str], k: int) -> float:\n        retrieved_k = retrieved[:k]\n        relevant_retrieved = len(set(retrieved_k) & relevant)\n        return relevant_retrieved \u002F len(relevant) if relevant else 0\n\n    def mrr(relevant: set, retrieved: List[str]) -> float:\n        for i, doc in enumerate(retrieved):\n            if doc in relevant:\n                return 1 \u002F (i + 1)\n        return 0\n\n    def ndcg_at_k(relevant: set, retrieved: List[str], k: int) -> float:\n        dcg = sum(\n            1 \u002F np.log2(i + 2) if doc in relevant else 0\n            for i, doc in enumerate(retrieved[:k])\n        )\n        ideal_dcg = sum(1 \u002F np.log2(i + 2) for i in range(min(len(relevant), k)))\n        return dcg \u002F ideal_dcg if ideal_dcg > 0 else 0\n\n    metrics = {\n        f\"precision@{k}\": [],\n        f\"recall@{k}\": [],\n        \"mrr\": [],\n        f\"ndcg@{k}\": []\n    }\n\n    for relevant, retrieved in zip(relevant_docs, retrieved_docs):\n        relevant_set = set(relevant)\n        metrics[f\"precision@{k}\"].append(precision_at_k(relevant_set, retrieved, k))\n        metrics[f\"recall@{k}\"].append(recall_at_k(relevant_set, retrieved, k))\n        metrics[\"mrr\"].append(mrr(relevant_set, retrieved))\n        metrics[f\"ndcg@{k}\"].append(ndcg_at_k(relevant_set, retrieved, k))\n\n    return {name: np.mean(values) for name, values in metrics.items()}\n\n\ndef compute_embedding_similarity(\n    embeddings1: np.ndarray,\n    embeddings2: np.ndarray,\n    metric: str = \"cosine\"\n) -> np.ndarray:\n    \"\"\"Compute similarity matrix between embedding sets.\"\"\"\n    if metric == \"cosine\":\n        # Normalize and compute dot product\n        norm1 = embeddings1 \u002F np.linalg.norm(embeddings1, axis=1, keepdims=True)\n        norm2 = embeddings2 \u002F np.linalg.norm(embeddings2, axis=1, keepdims=True)\n        return norm1 @ norm2.T\n    elif metric == \"euclidean\":\n        from scipy.spatial.distance import cdist\n        return -cdist(embeddings1, embeddings2, metric='euclidean')\n    elif metric == \"dot\":\n        return embeddings1 @ embeddings2.T\n    else:\n        raise ValueError(f\"Unknown metric: {metric}\")\n\n\ndef compare_embedding_models(\n    texts: List[str],\n    models: Dict[str, callable],\n    queries: List[str],\n    relevant_indices: List[List[int]],\n    k: int = 5\n) -> Dict[str, Dict[str, float]]:\n    \"\"\"Compare multiple embedding models on retrieval quality.\"\"\"\n    results = {}\n\n    for model_name, embed_fn in models.items():\n        # Embed all texts\n        doc_embeddings = np.array(embed_fn(texts))\n\n        retrieved_per_query = []\n        for query in queries:\n            query_embedding = np.array(embed_fn([query])[0])\n            # Compute similarities\n            similarities = compute_embedding_similarity(\n                query_embedding.reshape(1, -1),\n                doc_embeddings,\n                metric=\"cosine\"\n            )[0]\n            # Get top-k indices\n            top_k_indices = np.argsort(similarities)[::-1][:k]\n            retrieved_per_query.append([str(i) for i in top_k_indices])\n\n        # Convert relevant indices to string IDs\n        relevant_docs = [[str(i) for i in indices] for indices in relevant_indices]\n\n        results[model_name] = evaluate_retrieval_quality(\n            queries, relevant_docs, retrieved_per_query, k\n        )\n\n    return results\n```\n\n## Best Practices\n\n### Do's\n\n- **Match model to use case**: Code vs prose vs multilingual\n- **Chunk thoughtfully**: Preserve semantic boundaries\n- **Normalize embeddings**: For cosine similarity search\n- **Batch requests**: More efficient than one-by-one\n- **Cache embeddings**: Avoid recomputing for static content\n- **Use Voyage AI for Claude apps**: Recommended by Anthropic\n\n### Don'ts\n\n- **Don't ignore token limits**: Truncation loses information\n- **Don't mix embedding models**: Incompatible vector spaces\n- **Don't skip preprocessing**: Garbage in, garbage out\n- **Don't over-chunk**: Lose important context\n- **Don't forget metadata**: Essential for filtering and debugging\n",{"name":5,"description":7},"main","900bb95bbe72cdb94af6f5a620aa5081264b7b6d",".claude\u002Fmarketplaces\u002Fwshobson\u002Fplugins\u002Fllm-application-dev\u002Fskills\u002Fembedding-strategies",0,"https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up#readme","https:\u002F\u002Fgithub.com\u002Fsteph-frtech","2026-05-16 00:03:30",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add steph-frtech\u002Fclaude-code-up --skill embedding-strategies",{"tool":37,"command":38},"bunx","bunx skills add steph-frtech\u002Fclaude-code-up --skill embedding-strategies",{"tool":40,"command":41},"pnpm","pnpm dlx skills add steph-frtech\u002Fclaude-code-up --skill embedding-strategies","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fmarketplaces\u002Fwshobson\u002Fplugins\u002Fllm-application-dev\u002Fskills\u002Fembedding-strategies\u002FSKILL.md",true,[],[46,53,60,67,74,81],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":18},"01M72Y1BY6X8TX3DS19Y04NEBQ","example","One-line summary of what this skill does","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002Fskills\u002Fexample\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":18},"01M72Y1A38EYR8S9P1MBYDAQTW","writing-plans","Use when you have a spec or requirements for a multi-step task, before touching code","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsuperpowers__writing-plans\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":18},"01M72Y174QSV1B5NV1E4KWHQBR","using-git-worktrees","Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsuperpowers__using-git-worktrees\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":18},"01M72Y14SQRHHMKG316HGB2CGK","test-driven-development","Use when implementing any feature or bugfix, before writing implementation code","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsuperpowers__test-driven-development\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":18},"01M72Y127BCPRH3BRKPJC3Q3G2","systematic-debugging","Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsuperpowers__systematic-debugging\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":18},"01M72Y1090GJA6B67KPD60WPHH","subagent-driven-development","Use when executing implementation plans with independent tasks in the current session","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsuperpowers__subagent-driven-development\u002FSKILL.md",[],[]]