@nikeandocean/carbon-factor-matcher 0.2.0

package/src/carbon_factor_matcher/matcher.py

@@ -0,0 +1,795 @@
+"""
+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)