@nikeandocean/carbon-factor-matcher 0.2.0 → 0.3.0

package/src/carbon_factor_matcher/matcher.py

@@ -1,795 +0,0 @@
-"""
-Two-stage emission factor matching: hybrid retrieval + quality rating + LLM ranking.
-
-Stage 0: Unit pre-filter (hard constraint)
-Stage 1: Hybrid retrieval - keyword (0.3) + embedding (0.7)
-Stage 2: Quality rating + LLM fine ranking
-"""
-
-import logging
-import math
-import os
-import re
-from datetime import datetime
-from typing import Optional
-
-from openai import OpenAI
-
-from .config import LLMConfig
-from .factor_db import FactorDatabase
-from .models import Activity, Factor, MatchResult
-
-logger = logging.getLogger(__name__)
-
-# Default weights for hybrid retrieval
-KEYWORD_WEIGHT = 0.3
-EMBEDDING_WEIGHT = 0.7
-
-# Quality rating dimensions and weights (data quality assessment)
-QUALITY_WEIGHTS = {
-    "tech_representativeness": 0.3,    # 技术代表性
-    "geo_representativeness": 0.1,     # 地理代表性
-    "source_reliability": 0.4,         # 来源可靠性
-    "time_representativeness": 0.1,    # 时间代表性
-    "factor_type": 0.1,                # 因子类型
-}
-
-# Scoring criteria for quality dimensions
-TECH_SCORES = {"exact_match": 1, "type_match": 2, "unrelated": 3}
-GEO_SCORES = {"provincial": 1, "national": 2, "international": 3}
-SOURCE_SCORES = {"measured": 1, "estimated": 2, "unknown": 3}
-TIME_SCORES = {"recent": 1, "moderate": 2, "old": 3}
-FACTOR_TYPE_SCORES = {"lca": 1, "process": 2, "unknown": 3}
-
-
-class EmissionFactorMatcher:
-    """Two-stage emission factor matcher.
-
-    Stage 0: Unit pre-filter (hard constraint)
-    Stage 1: Hybrid retrieval - keyword (0.3) + embedding (0.7)
-    Stage 2: Quality rating + LLM fine ranking
-
-    Args:
-        factors: List of Factor to search.
-        config: LLMConfig instance. If None, uses embedding_model/chat_model
-            parameters or defaults.
-        embedding_model: Name of local sentence embedding model
-            (default: shibing624/text2vec-base-chinese).
-        chat_model: Name of chat model for re-ranking (default: deepseek-v4-flash).
-    """
-
-    def __init__(
-        self,
-        factors: list[Factor],
-        config: LLMConfig = None,
-        embedding_model: str = None,
-        chat_model: str = None,
-        skip_embedding: bool = False,
-    ):
-        self.factors = factors
-        self._by_id = {f.id: f for f in factors}
-
-        # Use config if provided, otherwise use parameters or defaults
-        if config is None:
-            config = LLMConfig(
-                embedding_model=embedding_model or "shibing624/text2vec-base-chinese",
-                model=chat_model or "deepseek-v4-flash",
-            )
-
-        self._config = config
-        self.embedding_model_name = config.embedding_model
-        self.chat_model = config.model
-
-        # Initialize OpenAI client for LLM (DeepSeek)
-        self.llm_client = OpenAI(
-            api_key=config.api_key or os.getenv("DeepSeek_API_KEY", "sk-placeholder"),
-            base_url=config.base_url,
-        )
-
-        # Initialize local sentence embedding model
-        self._embedding_model = None
-        if not skip_embedding:
-            self._init_embedding_model()
-
-        # Build factor texts (lightweight, no embedding computation)
-        self._factor_texts = [self._build_factor_text(f) for f in factors]
-        # Cache for on-demand embeddings (populated during hybrid_search)
-        self._embedding_cache: dict[int, list[float]] = {}
-
-    def _init_embedding_model(self):
-        """Initialize local sentence embedding model.
-
-        Tries local cache first (no network). Falls back to online download.
-        """
-        try:
-            from sentence_transformers import SentenceTransformer
-        except ImportError:
-            logger.warning("sentence-transformers not installed, embedding disabled")
-            self._embedding_model = None
-            return
-
-        # Try local cache first — no network calls, instant load
-        try:
-            self._embedding_model = SentenceTransformer(
-                self.embedding_model_name,
-                device="cpu",
-                local_files_only=True,
-            )
-            logger.info(f"Loaded embedding model from cache: {self.embedding_model_name}")
-            return
-        except Exception:
-            logger.info("Model not in cache, downloading from HuggingFace...")
-
-        # Fallback: download from HuggingFace
-        try:
-            self._embedding_model = SentenceTransformer(
-                self.embedding_model_name,
-                device="cpu",
-            )
-            logger.info(f"Downloaded embedding model: {self.embedding_model_name}")
-        except Exception as e:
-            logger.warning(f"Failed to load embedding model: {e}")
-            self._embedding_model = None
-
-    def _compute_factor_embeddings(self) -> list[list[float]]:
-        """Pre-compute embeddings for all factors."""
-        if self._embedding_model is None:
-            return [[] for _ in self.factors]
-
-        try:
-            embeddings = self._embedding_model.encode(
-                self._factor_texts,
-                batch_size=32,
-                show_progress_bar=False,
-            )
-            return [emb.tolist() for emb in embeddings]
-        except Exception as e:
-            logger.warning(f"Failed to compute factor embeddings: {e}")
-            return [[] for _ in self.factors]
-
-    def _build_factor_text(self, factor: Factor) -> str:
-        """Build searchable text from factor fields."""
-        parts = [
-            factor.name,
-            factor.category,
-            factor.applicability,
-            factor.geography.get("location", factor.geography.get("country", "")),
-        ]
-        return " ".join(p for p in parts if p)
-
-    def _unit_match(self, factor: Factor, target_unit: str) -> bool:
-        """Hard constraint: check if factor unit matches target unit."""
-        if not target_unit:
-            return True
-
-        factor_unit = factor.unit.lower().strip()
-        target = target_unit.lower().strip()
-
-        if factor_unit == target:
-            return True
-
-        unit_aliases = {
-            "kg co2e": ["kg co2 eq", "kg co2-eq", "kg二氧化碳当量"],
-            "t co2e": ["t co2 eq", "t co2-eq", "ton co2e", "吨二氧化碳当量"],
-            "kg": ["千克", "公斤"],
-            "g": ["克"],
-            "t": ["ton", "tonne", "吨"],
-            "kwh": ["千瓦时", "度"],
-            "mj": ["兆焦"],
-            "m3": ["立方米", "立方"],
-            "m2": ["平方米", "平米"],
-            "l": ["liter", "litre", "升"],
-            "t*km": ["吨公里", "吨千米"],
-            "kbq": ["千贝克勒尔"],
-        }
-
-        for canonical, aliases in unit_aliases.items():
-            if target == canonical or target in aliases:
-                return factor_unit == canonical or factor_unit in aliases
-
-        return False
-
-    def _keyword_score(self, factor: Factor, query: str) -> float:
-        """Compute keyword match score using exact and partial matching."""
-        query_lower = query.lower()
-        factor_text = self._build_factor_text(factor).lower()
-
-        if query_lower == factor.name.lower():
-            return 1.0
-
-        if query_lower in factor_text:
-            return 0.8
-
-        query_terms = query_lower.split()
-        if not query_terms:
-            return 0.0
-
-        matched = sum(1 for t in query_terms if t in factor_text)
-        return matched / len(query_terms)
-
-    def _compute_embedding_similarity(
-        self, query: str, factor_idx: int
-    ) -> float:
-        """Compute embedding similarity between query and factor (uses cache)."""
-        if self._embedding_model is None:
-            return 0.0
-
-        factor_emb = self._embedding_cache.get(factor_idx)
-        if not factor_emb:
-            return 0.0
-
-        try:
-            query_emb = self._embedding_model.encode([query])[0].tolist()
-            return self._cosine_similarity(query_emb, factor_emb)
-        except Exception:
-            return 0.0
-
-    def _batch_encode_factors(self, indices: list[int]) -> None:
-        """Batch-encode factors and cache their embeddings."""
-        if self._embedding_model is None:
-            return
-        uncached = [i for i in indices if i not in self._embedding_cache]
-        if not uncached:
-            return
-        texts = [self._factor_texts[i] for i in uncached]
-        embeddings = self._embedding_model.encode(
-            texts, batch_size=64, show_progress_bar=False,
-        )
-        for idx, emb in zip(uncached, embeddings):
-            self._embedding_cache[idx] = emb.tolist()
-
-    def _cosine_similarity(self, a: list[float], b: list[float]) -> float:
-        """Compute cosine similarity between two vectors."""
-        dot = sum(x * y for x, y in zip(a, b))
-        norm_a = math.sqrt(sum(x * x for x in a))
-        norm_b = math.sqrt(sum(x * x for x in b))
-        if norm_a == 0 or norm_b == 0:
-            return 0.0
-        return dot / (norm_a * norm_b)
-
-    def _compute_quality_ratings(self, factor: Factor, query: str) -> dict:
-        """Compute quality ratings based on the 5-dimension assessment system."""
-        current_year = datetime.now().year
-        ratings = {}
-
-        # 1. 技术代表性 (Technology Representativeness)
-        query_lower = query.lower()
-        factor_name = factor.name.lower()
-        factor_applicability = (factor.applicability or "").lower()
-
-        if query_lower in factor_name or factor_name in query_lower:
-            ratings["tech_representativeness"] = TECH_SCORES["exact_match"]
-        elif any(t in factor_applicability for t in query_lower.split()):
-            ratings["tech_representativeness"] = TECH_SCORES["type_match"]
-        else:
-            ratings["tech_representativeness"] = TECH_SCORES["unrelated"]
-
-        # 2. 地理代表性 (Geographic Representativeness)
-        location = factor.geography.get("location", "").lower()
-        if any(kw in location for kw in ["省", "市", "区", "province", "city"]):
-            ratings["geo_representativeness"] = GEO_SCORES["provincial"]
-        elif any(kw in location for kw in ["中国", "china", "美国", "usa", "欧洲", "europe"]):
-            ratings["geo_representativeness"] = GEO_SCORES["national"]
-        else:
-            ratings["geo_representativeness"] = GEO_SCORES["international"]
-
-        # 3. 来源可靠性 (Source Reliability)
-        source_lower = factor.source.lower()
-        if any(kw in source_lower for kw in ["实测", "测量", "实绩", "measured", "actual"]):
-            ratings["source_reliability"] = SOURCE_SCORES["measured"]
-        elif any(kw in source_lower for kw in ["估算", "计算", "模型", "estimated", "modeled"]):
-            ratings["source_reliability"] = SOURCE_SCORES["estimated"]
-        else:
-            ratings["source_reliability"] = SOURCE_SCORES["unknown"]
-
-        # 4. 时间代表性 (Time Representativeness)
-        year = factor.source_year
-        if year == 0:
-            ratings["time_representativeness"] = TIME_SCORES["old"]
-        else:
-            age = current_year - year
-            if age <= 3:
-                ratings["time_representativeness"] = TIME_SCORES["recent"]
-            elif age <= 10:
-                ratings["time_representativeness"] = TIME_SCORES["moderate"]
-            else:
-                ratings["time_representativeness"] = TIME_SCORES["old"]
-
-        # 5. 因子类型 (Factor Type)
-        category = factor.category.lower()
-        if any(kw in category for kw in ["lca", "生命周期", "life cycle"]):
-            ratings["factor_type"] = FACTOR_TYPE_SCORES["lca"]
-        elif any(kw in category for kw in ["过程", "process", "清单", "inventory"]):
-            ratings["factor_type"] = FACTOR_TYPE_SCORES["process"]
-        else:
-            ratings["factor_type"] = FACTOR_TYPE_SCORES["unknown"]
-
-        return ratings
-
-    def _compute_quality_score(self, quality_ratings: dict) -> float:
-        """Compute weighted quality score from dimension ratings.
-
-        Lower rating = better quality, so we invert the score.
-        Score = 1 - (weighted_average / 3)
-        """
-        weighted_sum = sum(
-            quality_ratings[dim] * weight
-            for dim, weight in QUALITY_WEIGHTS.items()
-        )
-        return 1.0 - (weighted_sum - 1) / 2.0
-
-    def _build_quality_description(self, quality_ratings: dict) -> str:
-        """Build human-readable quality description."""
-        dim_names = {
-            "tech_representativeness": "技术代表性",
-            "geo_representativeness": "地理代表性",
-            "source_reliability": "来源可靠性",
-            "time_representativeness": "时间代表性",
-            "factor_type": "因子类型",
-        }
-        level_labels = {1: "优", 2: "中", 3: "差"}
-
-        parts = []
-        for dim, rating in quality_ratings.items():
-            name = dim_names.get(dim, dim)
-            level = level_labels.get(rating, "未知")
-            parts.append(f"{name}: {level}({rating})")
-
-        return " | ".join(parts)
-
-    def _format_factor_for_llm(
-        self, idx: int, factor: Factor, quality_ratings: dict
-    ) -> str:
-        """Format a single factor for LLM re-ranking prompt."""
-        quality_desc = self._build_quality_description(quality_ratings)
-        return f"""[{idx}] {factor.name}
-  分类: {factor.category}
-  适用性: {factor.applicability or 'N/A'}
-  地理: {factor.geography.get('location', 'N/A')}
-  单位: {factor.unit}
-  数值: {factor.value}
-  来源: {factor.source} ({factor.source_year})
-  数据质量: {quality_desc}"""
-
-    def search(self, query: str) -> list[Factor]:
-        """Simple keyword search across factor name, category, applicability."""
-        query_lower = query.lower()
-        return [
-            f for f in self.factors
-            if query_lower in f.name.lower()
-            or query_lower in f.category.lower()
-            or query_lower in f.applicability.lower()
-        ]
-
-    def get_by_id(self, factor_id: str) -> Factor | None:
-        """Get a factor by ID."""
-        return self._by_id.get(factor_id)
-
-    def hybrid_search(
-        self,
-        query: str,
-        target_unit: str = "",
-        top_k: int = 20,
-        keyword_top_n: int = 200,
-    ) -> list[dict]:
-        """Stage 0 + Stage 1: Unit pre-filter + Hybrid retrieval.
-
-        Two-stage optimization: keyword pre-filter to keyword_top_n,
-        then compute embeddings only on the narrowed candidates.
-
-        Args:
-            query: User query for emission factor.
-            target_unit: Required unit (hard constraint).
-            top_k: Number of candidates to return.
-            keyword_top_n: Top-N candidates from keyword stage to pass
-                to embedding stage. Lower = faster, higher = more thorough.
-
-        Returns:
-            Top-k candidates with hybrid scores.
-        """
-        # Stage 0: Unit pre-filter
-        if target_unit:
-            eligible_factors = [
-                (i, f) for i, f in enumerate(self.factors)
-                if self._unit_match(f, target_unit)
-            ]
-            if not eligible_factors:
-                logger.warning(f"No factors match unit '{target_unit}'")
-                return []
-        else:
-            eligible_factors = list(enumerate(self.factors))
-
-        # Stage 1a: Keyword scoring
-        keyword_results = []
-        for idx, factor in eligible_factors:
-            score = self._keyword_score(factor, query)
-            keyword_results.append((idx, score))
-
-        keyword_results.sort(key=lambda x: x[1], reverse=True)
-        max_kw = keyword_results[0][1] if keyword_results else 1.0
-        keyword_scores = {
-            idx: score / max_kw if max_kw > 0 else 0.0
-            for idx, score in keyword_results
-        }
-
-        # Stage 1b: Narrow candidates before embedding
-        if self._embedding_model is not None and len(keyword_results) > keyword_top_n:
-            narrowed = keyword_results[:keyword_top_n]
-            logger.info(
-                f"Keyword pre-filter: {len(keyword_results)} -> {keyword_top_n} candidates"
-            )
-        else:
-            narrowed = keyword_results
-
-        # Batch-encode narrowed candidates, then compute similarities
-        embedding_scores = {}
-        if self._embedding_model is not None:
-            narrowed_indices = [idx for idx, _ in narrowed]
-            self._batch_encode_factors(narrowed_indices)
-            query_emb = self._embedding_model.encode([query])[0].tolist()
-            for idx, _ in narrowed:
-                factor_emb = self._embedding_cache.get(idx, [])
-                if factor_emb:
-                    embedding_scores[idx] = self._cosine_similarity(query_emb, factor_emb)
-                else:
-                    embedding_scores[idx] = 0.0
-
-        # Combine scores
-        results = []
-        for idx, _ in narrowed:
-            factor = self.factors[idx]
-            kw_score = keyword_scores.get(idx, 0.0)
-            emb_score = embedding_scores.get(idx, 0.0)
-
-            if self._embedding_model is None:
-                hybrid = kw_score
-            else:
-                hybrid = KEYWORD_WEIGHT * kw_score + EMBEDDING_WEIGHT * emb_score
-
-            quality_ratings = self._compute_quality_ratings(factor, query)
-            quality_score = self._compute_quality_score(quality_ratings)
-
-            results.append({
-                "factor": factor,
-                "keyword_score": kw_score,
-                "embedding_score": emb_score,
-                "hybrid_score": hybrid,
-                "quality_ratings": quality_ratings,
-                "quality_score": quality_score,
-                "llm_reasoning": "",
-                "final_score": 0.0,
-            })
-
-        results.sort(key=lambda x: x["hybrid_score"], reverse=True)
-        return results[:top_k]
-
-    def match(
-        self,
-        query: str,
-        target_unit: str = "",
-        top_k: int = 5,
-    ) -> MatchResult | None:
-        """Full two-stage matching pipeline.
-
-        Stage 0: Unit pre-filter
-        Stage 1: Hybrid retrieval (keyword 0.3 + embedding 0.7)
-        Stage 2: Quality rating + LLM fine ranking
-
-        Args:
-            query: User query for emission factor.
-            target_unit: Required unit (hard constraint).
-            top_k: Number of final results to return.
-
-        Returns:
-            MatchResult with best factor, reason, confidence, and candidates, or None if no matches.
-        """
-        candidates = self.hybrid_search(query, target_unit, top_k=20)
-
-        if not candidates:
-            return None
-
-        ranked = self._llm_rank(query, candidates)
-
-        if not ranked:
-            return None
-
-        # Return best match as MatchResult
-        best = ranked[0]
-        return MatchResult(
-            factor=best["factor"],
-            reason=best.get("llm_reasoning", ""),
-            confidence=best.get("final_score", 0.0),
-            candidates=[c["factor"] for c in ranked[:top_k]],
-        )
-
-    def match_activity(
-        self,
-        activity: Activity,
-        top_k: int = 5,
-    ) -> MatchResult | None:
-        """Match emission factor using structured activity data.
-
-        Args:
-            activity: Activity object with name, location, time, unit, etc.
-            top_k: Number of final results to return.
-
-        Returns:
-            MatchResult with best factor, reason, confidence, and candidates, or None if no matches.
-        """
-        query = activity.to_query()
-        candidates = self.hybrid_search(query, activity.unit, top_k=20)
-
-        if not candidates:
-            return None
-
-        # Re-compute quality ratings using activity fields
-        for c in candidates:
-            c["quality_ratings"] = self._compute_quality_ratings_for_activity(
-                c["factor"], activity
-            )
-            c["quality_score"] = self._compute_quality_score(c["quality_ratings"])
-
-        ranked = self._llm_rank_activity(activity, candidates)
-
-        if not ranked:
-            return None
-
-        # Return best match as MatchResult
-        best = ranked[0]
-        return MatchResult(
-            factor=best["factor"],
-            reason=best.get("llm_reasoning", ""),
-            confidence=best.get("final_score", 0.0),
-            candidates=[c["factor"] for c in ranked[:top_k]],
-        )
-
-    def _compute_quality_ratings_for_activity(
-        self, factor: Factor, activity: Activity
-    ) -> dict:
-        """Compute quality ratings using structured activity data."""
-        current_year = datetime.now().year
-        ratings = {}
-
-        # 1. 技术代表性 - compare activity name/technology with factor
-        activity_name = activity.name.lower()
-        factor_name = factor.name.lower()
-        factor_applicability = (factor.applicability or "").lower()
-        activity_tech = (activity.technology or "").lower()
-
-        if activity_name in factor_name or factor_name in activity_name:
-            ratings["tech_representativeness"] = TECH_SCORES["exact_match"]
-        elif activity_tech and activity_tech in factor_applicability:
-            ratings["tech_representativeness"] = TECH_SCORES["exact_match"]
-        elif any(t in factor_applicability for t in activity_name.split()):
-            ratings["tech_representativeness"] = TECH_SCORES["type_match"]
-        else:
-            ratings["tech_representativeness"] = TECH_SCORES["unrelated"]
-
-        # 2. 地理代表性 - compare activity location with factor geography
-        factor_location = factor.geography.get("location", "").lower()
-        activity_location = activity.location.lower()
-
-        if activity_location and activity_location in factor_location:
-            ratings["geo_representativeness"] = GEO_SCORES["provincial"]
-        elif any(kw in factor_location for kw in ["省", "市", "区", "province", "city"]):
-            ratings["geo_representativeness"] = GEO_SCORES["provincial"]
-        elif any(kw in factor_location for kw in ["中国", "china"]):
-            ratings["geo_representativeness"] = GEO_SCORES["national"]
-        else:
-            ratings["geo_representativeness"] = GEO_SCORES["international"]
-
-        # 3. 来源可靠性
-        source_lower = factor.source.lower()
-        if any(kw in source_lower for kw in ["实测", "测量", "实绩", "measured", "actual"]):
-            ratings["source_reliability"] = SOURCE_SCORES["measured"]
-        elif any(kw in source_lower for kw in ["估算", "计算", "模型", "estimated", "modeled"]):
-            ratings["source_reliability"] = SOURCE_SCORES["estimated"]
-        else:
-            ratings["source_reliability"] = SOURCE_SCORES["unknown"]
-
-        # 4. 时间代表性 - compare activity time with factor source_year
-        factor_year = factor.source_year
-        if activity.time and factor_year > 0:
-            try:
-                activity_year = int(activity.time[:4])
-                age = activity_year - factor_year
-                if abs(age) <= 3:
-                    ratings["time_representativeness"] = TIME_SCORES["recent"]
-                elif abs(age) <= 10:
-                    ratings["time_representativeness"] = TIME_SCORES["moderate"]
-                else:
-                    ratings["time_representativeness"] = TIME_SCORES["old"]
-            except ValueError:
-                ratings["time_representativeness"] = TIME_SCORES["old"]
-        elif factor_year == 0:
-            ratings["time_representativeness"] = TIME_SCORES["old"]
-        else:
-            age = current_year - factor_year
-            if age <= 3:
-                ratings["time_representativeness"] = TIME_SCORES["recent"]
-            elif age <= 10:
-                ratings["time_representativeness"] = TIME_SCORES["moderate"]
-            else:
-                ratings["time_representativeness"] = TIME_SCORES["old"]
-
-        # 5. 因子类型
-        category = factor.category.lower()
-        if any(kw in category for kw in ["lca", "生命周期", "life cycle"]):
-            ratings["factor_type"] = FACTOR_TYPE_SCORES["lca"]
-        elif any(kw in category for kw in ["过程", "process", "清单", "inventory"]):
-            ratings["factor_type"] = FACTOR_TYPE_SCORES["process"]
-        else:
-            ratings["factor_type"] = FACTOR_TYPE_SCORES["unknown"]
-
-        return ratings
-
-    def _llm_rank_activity(
-        self, activity: Activity, candidates: list[dict]
-    ) -> list[dict]:
-        """LLM fine ranking with structured activity context."""
-        factor_descriptions = []
-        for i, c in enumerate(candidates, 1):
-            desc = self._format_factor_for_llm(i, c["factor"], c["quality_ratings"])
-            factor_descriptions.append(desc)
-
-        factors_text = "\n\n".join(factor_descriptions)
-
-        prompt = f"""请根据用户活动数据，从候选列表中选择最匹配的排放因子。
-
-用户活动数据:
-  活动名称: {activity.name}
-  地点: {activity.location or '未指定'}
-  时间: {activity.time or '未指定'}
-  工艺: {activity.technology or '未指定'}
-  单位: {activity.unit}
-  数量: {activity.amount or '未指定'}
-
-候选因子（含数据质量评级）:
-{factors_text}
-
-选择原则:
-1. 地理位置必须匹配（优先同国家/地区）
-2. 技术规格匹配（电压等级、温度、压力等）
-3. 当用户明确指定规格时（如"230V"、"低电压"、"1kV-60kV"），严格匹配
-4. 当用户未指定规格时，保持默认排序（第一个候选）不变
-5. 仅当有明确理由时才改变排序
-6. 单位必须完全匹配
-7. 数据质量评级越高越好
-
-请返回最匹配的因子编号（多个用逗号分隔），并简要说明选择理由。
-格式: 1,3,5 | 理由: ..."""
-
-        try:
-            response = self.llm_client.chat.completions.create(
-                model=self.chat_model,
-                messages=[
-                    {
-                        "role": "system",
-                        "content": (
-                            "你是碳排放因子匹配专家。"
-                            "数据质量评级说明：技术代表性/地理代表性/来源可靠性/时间代表性/因子类型，"
-                            "1=优, 2=中, 3=差。来源可靠性权重最高(0.4)。"
-                            "优先选择：地理匹配、时间接近、来源可靠的因子。"
-                            "技术规格匹配：仔细对比用户查询与因子名称中的电压等级、温度、压力等参数。"
-                            "重要：默认选择第一个候选（已按相关性排序）。仅当能明确证明第一个候选"
-                            "在技术规格上不匹配时才改变排序（如用户明确写了'230V'但候选是'1kV-60kV'）。"
-                        ),
-                    },
-                    {"role": "user", "content": prompt},
-                ],
-                temperature=0.1,
-            )
-
-            answer = response.choices[0].message.content or ""
-            return self._parse_ranked_results(candidates, answer)
-
-        except Exception as e:
-            logger.warning(f"LLM ranking failed: {e}, using hybrid score")
-            return candidates
-
-    def _llm_rank(self, query: str, candidates: list[dict]) -> list[dict]:
-        """Stage 2: LLM fine ranking with quality ratings context."""
-        factor_descriptions = []
-        for i, c in enumerate(candidates, 1):
-            desc = self._format_factor_for_llm(i, c["factor"], c["quality_ratings"])
-            factor_descriptions.append(desc)
-
-        factors_text = "\n\n".join(factor_descriptions)
-        units = list(set(c["factor"].unit for c in candidates))
-        units_text = ", ".join(units[:3])
-
-        prompt = f"""请根据用户查询，从候选列表中选择最匹配的排放因子。
-
-用户查询: {query}
-可选单位: {units_text}
-
-候选因子（含数据质量评级）:
-{factors_text}
-
-选择原则:
-1. 地理位置必须匹配（优先同国家/地区）
-2. 技术规格匹配（电压等级、温度、压力等）
-3. 当用户明确指定规格时（如"230V"、"低电压"、"1kV-60kV"），严格匹配
-4. 当用户未指定规格时，保持默认排序（第一个候选）不变
-5. 仅当有明确理由时才改变排序
-6. 单位必须完全匹配
-7. 数据质量评级越高越好
-
-请返回最匹配的因子编号（多个用逗号分隔），并简要说明选择理由。
-格式: 1,3,5 | 理由: ..."""
-
-        try:
-            response = self.llm_client.chat.completions.create(
-                model=self.chat_model,
-                messages=[
-                    {
-                        "role": "system",
-                        "content": (
-                            "你是碳排放因子匹配专家。"
-                            "数据质量评级说明：技术代表性/地理代表性/来源可靠性/时间代表性/因子类型，"
-                            "1=优, 2=中, 3=差。来源可靠性权重最高(0.4)。"
-                            "优先选择：地理匹配、时间接近、来源可靠的因子。"
-                            "技术规格匹配：仔细对比用户查询与因子名称中的电压等级、温度、压力等参数。"
-                            "重要：默认选择第一个候选（已按相关性排序）。仅当能明确证明第一个候选"
-                            "在技术规格上不匹配时才改变排序（如用户明确写了'230V'但候选是'1kV-60kV'）。"
-                        ),
-                    },
-                    {"role": "user", "content": prompt},
-                ],
-                temperature=0.1,
-            )
-
-            answer = response.choices[0].message.content or ""
-            return self._parse_ranked_results(candidates, answer)
-
-        except Exception as e:
-            logger.warning(f"LLM ranking failed: {e}, using hybrid score")
-            return candidates
-
-    def _parse_ranked_results(
-        self, candidates: list[dict], llm_answer: str
-    ) -> list[dict]:
-        """Parse LLM ranking answer and reorder candidates."""
-        numbers = re.findall(
-            r"\d+",
-            llm_answer.split("|")[0] if "|" in llm_answer else llm_answer,
-        )
-
-        ranked = []
-        seen = set()
-
-        for num_str in numbers:
-            try:
-                idx = int(num_str) - 1
-                if 0 <= idx < len(candidates) and idx not in seen:
-                    candidates[idx]["llm_reasoning"] = llm_answer
-                    candidates[idx]["final_score"] = (
-                        candidates[idx]["hybrid_score"] * 0.5
-                        + candidates[idx]["quality_score"] * 0.5
-                    )
-                    ranked.append(candidates[idx])
-                    seen.add(idx)
-            except (ValueError, IndexError):
-                continue
-
-        for i, c in enumerate(candidates):
-            if i not in seen:
-                c["final_score"] = c["hybrid_score"] * 0.3
-                ranked.append(c)
-
-        return ranked
-
-
-def create_matcher(db: Optional[FactorDatabase] = None) -> EmissionFactorMatcher:
-    """Create a matcher with factors from the database.
-
-    Args:
-        db: FactorDatabase instance. If None, creates a new one.
-
-    Returns:
-        Initialized EmissionFactorMatcher.
-    """
-    if db is None:
-        db = FactorDatabase()
-
-    return EmissionFactorMatcher(factors=db.factors)