sycommon-python-lib 0.1.46__py3-none-any.whl → 0.1.57b1__py3-none-any.whl

sycommon/llm/llm_tokens.py

@@ -0,0 +1,119 @@
+from typing import Any
+from langchain_core.callbacks import AsyncCallbackHandler
+from langchain_core.outputs.llm_result import LLMResult
+from sycommon.logging.kafka_log import SYLogger
+
+
+class TokensCallbackHandler(AsyncCallbackHandler):
+    """
+    继承AsyncCallbackHandler的Token统计处理器
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.input_tokens = 0
+        self.output_tokens = 0
+        self.total_tokens = 0
+        self.usage_metadata = {}
+        self.reset()
+
+    def reset(self):
+        """重置Token统计数据"""
+        self.input_tokens = 0
+        self.output_tokens = 0
+        self.total_tokens = 0
+        self.usage_metadata = {
+            "input_tokens": 0,
+            "output_tokens": 0,
+            "total_tokens": 0
+        }
+
+    # ========== 同步回调方法（兼容签名） ==========
+    def on_llm_end(
+        self,
+        response: LLMResult,
+        **kwargs: Any,
+    ) -> None:
+        """同步LLM调用结束时的回调"""
+        self._parse_token_usage(response)
+
+    # ========== 异步回调方法（兼容签名） ==========
+    async def on_llm_end(
+        self,
+        response: LLMResult,
+        **kwargs: Any,
+    ) -> None:
+        """异步LLM调用结束时的回调"""
+        self._parse_token_usage(response)
+
+    def _parse_token_usage(self, response: LLMResult) -> None:
+        """
+        通用Token解析逻辑，不依赖特定类结构
+        兼容各种LLM响应格式
+        """
+        try:
+            # 情况1: 标准LangChain响应（有llm_output属性）
+            if response.llm_output:
+                llm_output = response.llm_output
+                self._parse_from_llm_output(llm_output)
+
+            # 情况2: 包含generations的响应
+            elif response.generations:
+                self._parse_from_generations(response.generations)
+
+            # 计算总Token
+            if self.total_tokens <= 0:
+                self.total_tokens = self.input_tokens + self.output_tokens
+
+            # 更新metadata
+            self.usage_metadata = {
+                "input_tokens": self.input_tokens,
+                "output_tokens": self.output_tokens,
+                "total_tokens": self.total_tokens
+            }
+
+            SYLogger.debug(
+                f"Token统计成功 - 输入: {self.input_tokens}, 输出: {self.output_tokens}")
+
+        except Exception as e:
+            SYLogger.warning(f"Token解析失败: {str(e)}", exc_info=True)
+            self.reset()
+
+    def _parse_from_llm_output(self, llm_output: dict) -> None:
+        """从llm_output字典解析Token信息"""
+        if not isinstance(llm_output, dict):
+            return
+
+        # OpenAI标准格式
+        if 'token_usage' in llm_output:
+            token_usage = llm_output['token_usage']
+            self.input_tokens = token_usage.get(
+                'prompt_tokens', token_usage.get('input_tokens', 0))
+            self.output_tokens = token_usage.get(
+                'completion_tokens', token_usage.get('output_tokens', 0))
+            self.total_tokens = token_usage.get('total_tokens', 0)
+
+        # 直接包含Token信息
+        else:
+            self.input_tokens = llm_output.get(
+                'input_tokens', llm_output.get('prompt_tokens', 0))
+            self.output_tokens = llm_output.get(
+                'output_tokens', llm_output.get('completion_tokens', 0))
+            self.total_tokens = token_usage.get('total_tokens', 0)
+
+    def _parse_from_generations(self, generations: list) -> None:
+        """从generations列表解析Token信息"""
+        if not isinstance(generations, list) or len(generations) == 0:
+            return
+
+        # 遍历generation信息
+        for gen_group in generations:
+            for generation in gen_group:
+                if hasattr(generation, 'generation_info') and generation.generation_info:
+                    gen_info = generation.generation_info
+                    self.input_tokens = gen_info.get(
+                        'input_tokens', gen_info.get('prompt_tokens', 0))
+                    self.output_tokens = gen_info.get(
+                        'output_tokens', gen_info.get('completion_tokens', 0))
+                    self.total_tokens = gen_info.get('total_tokens', 0)
+                    return

sycommon/llm/struct_token.py

@@ -0,0 +1,192 @@
+from typing import Dict, List, Optional, Any
+from langfuse import Langfuse, LangfuseSpan, propagate_attributes
+from sycommon.llm.llm_logger import LLMLogger
+from langchain_core.runnables import Runnable, RunnableConfig
+from langchain_core.messages import BaseMessage, HumanMessage
+from sycommon.llm.llm_tokens import TokensCallbackHandler
+from sycommon.logging.kafka_log import SYLogger
+from sycommon.tools.env import get_env_var
+from sycommon.tools.merge_headers import get_header_value
+
+
+class StructuredRunnableWithToken(Runnable):
+    """带Token统计的Runnable类"""
+
+    def __init__(self, retry_chain: Runnable, langfuse: Optional[Langfuse]):
+        super().__init__()
+        self.retry_chain = retry_chain
+        self.langfuse = langfuse
+
+    def _adapt_input(self, input: Any) -> List[BaseMessage]:
+        """适配输入格式"""
+        if isinstance(input, list) and all(isinstance(x, BaseMessage) for x in input):
+            return input
+        elif isinstance(input, BaseMessage):
+            return [input]
+        elif isinstance(input, str):
+            return [HumanMessage(content=input)]
+        elif isinstance(input, dict) and "input" in input:
+            return [HumanMessage(content=str(input["input"]))]
+        else:
+            raise ValueError(f"不支持的输入格式：{type(input)}")
+
+    def _get_callback_config(
+        self,
+        config: Optional[RunnableConfig] = None,
+        trace_id: Optional[str] = None,
+        user_id: Optional[str] = None
+    ) -> tuple[RunnableConfig, TokensCallbackHandler]:
+        """构建包含Token统计和metadata的回调配置"""
+        token_handler = TokensCallbackHandler()
+
+        if config is None:
+            processed_config = {"callbacks": [], "metadata": {}}
+        else:
+            processed_config = config.copy()
+            if "callbacks" not in processed_config:
+                processed_config["callbacks"] = []
+            if "metadata" not in processed_config:
+                processed_config["metadata"] = {}
+
+        # 添加 Langfuse metadata
+        if trace_id:
+            processed_config["metadata"]["langfuse_session_id"] = trace_id
+        if user_id:
+            processed_config["metadata"]["langfuse_user_id"] = user_id
+
+        callbacks = processed_config["callbacks"]
+        if not any(isinstance(cb, LLMLogger) for cb in callbacks):
+            callbacks.append(LLMLogger())
+        callbacks.append(token_handler)
+
+        callback_types = {}
+        unique_callbacks = []
+        for cb in callbacks:
+            cb_type = type(cb)
+            if cb_type not in callback_types:
+                callback_types[cb_type] = cb
+                unique_callbacks.append(cb)
+
+        processed_config["callbacks"] = unique_callbacks
+
+        return processed_config, token_handler
+
+    def invoke(self, input: Any, config: Optional[RunnableConfig] = None, **kwargs) -> Dict[str, Any]:
+        # 获取 trace_id 和 user_id
+        trace_id = SYLogger.get_trace_id()
+        userid = get_header_value(SYLogger.get_headers(), "x-userid-header")
+        syVersion = get_header_value(SYLogger.get_headers(), "s-y-version")
+        user_id = userid or syVersion or get_env_var('VERSION')
+
+        # 判断是否启用 Langfuse
+        if self.langfuse:
+            try:
+                with self.langfuse.start_as_current_observation(as_type="span", name="invoke") as span:
+                    with propagate_attributes(session_id=trace_id, user_id=user_id):
+                        span.update_trace(user_id=user_id, session_id=trace_id)
+                        return self._execute_chain(input, config, trace_id, user_id, span)
+            except Exception as e:
+                # Langfuse 跟踪失败不应阻断业务，降级执行
+                SYLogger.error(f"Langfuse 同步跟踪失败: {str(e)}", exc_info=True)
+                return self._execute_chain(input, config, trace_id, user_id, None)
+        else:
+            # 未启用 Langfuse，直接执行业务逻辑
+            return self._execute_chain(input, config, trace_id, user_id, None)
+
+    async def ainvoke(self, input: Any, config: Optional[RunnableConfig] = None, **kwargs) -> Dict[str, Any]:
+        # 获取 trace_id 和 user_id
+        trace_id = SYLogger.get_trace_id()
+        userid = get_header_value(SYLogger.get_headers(), "x-userid-header")
+        syVersion = get_header_value(SYLogger.get_headers(), "s-y-version")
+        user_id = userid or syVersion or get_env_var('VERSION')
+
+        # 判断是否启用 Langfuse
+        if self.langfuse:
+            try:
+                with self.langfuse.start_as_current_observation(as_type="span", name="ainvoke") as span:
+                    with propagate_attributes(session_id=trace_id, user_id=user_id):
+                        span.update_trace(user_id=user_id, session_id=trace_id)
+                        return await self._aexecute_chain(input, config, trace_id, user_id, span)
+            except Exception as e:
+                # Langfuse 跟踪失败不应阻断业务，降级执行
+                SYLogger.error(f"Langfuse 异步跟踪失败: {str(e)}", exc_info=True)
+                return await self._aexecute_chain(input, config, trace_id, user_id, None)
+        else:
+            # 未启用 Langfuse，直接执行业务逻辑
+            return await self._aexecute_chain(input, config, trace_id, user_id, None)
+
+    def _execute_chain(
+        self,
+        input: Any,
+        config: Optional[RunnableConfig],
+        trace_id: str,
+        user_id: str,
+        span: LangfuseSpan
+    ) -> Dict[str, Any]:
+        """执行实际的调用逻辑 (同步)"""
+        try:
+            processed_config, token_handler = self._get_callback_config(
+                config,
+                trace_id=trace_id,
+                user_id=user_id
+            )
+
+            adapted_input = self._adapt_input(input)
+            input_data = {"messages": adapted_input}
+
+            if span:
+                span.update_trace(input=input_data)
+
+            structured_result = self.retry_chain.invoke(
+                input_data,
+                config=processed_config
+            )
+
+            if span:
+                span.update_trace(output=structured_result)
+
+            token_usage = token_handler.usage_metadata
+            structured_result._token_usage_ = token_usage
+
+            return structured_result
+        except Exception as e:
+            SYLogger.error(f"同步LLM调用失败: {str(e)}", exc_info=True)
+            return None
+
+    async def _aexecute_chain(
+        self,
+        input: Any,
+        config: Optional[RunnableConfig],
+        trace_id: str,
+        user_id: str,
+        span: LangfuseSpan
+    ) -> Dict[str, Any]:
+        """执行实际的调用逻辑 (异步)"""
+        try:
+            processed_config, token_handler = self._get_callback_config(
+                config,
+                trace_id=trace_id,
+                user_id=user_id
+            )
+
+            adapted_input = self._adapt_input(input)
+            input_data = {"messages": adapted_input}
+
+            if span:
+                span.update_trace(input=input_data)
+
+            structured_result = await self.retry_chain.ainvoke(
+                input_data,
+                config=processed_config
+            )
+
+            if span:
+                span.update_trace(output=structured_result)
+
+            token_usage = token_handler.usage_metadata
+            structured_result._token_usage_ = token_usage
+
+            return structured_result
+        except Exception as e:
+            SYLogger.error(f"异步LLM调用失败: {str(e)}", exc_info=True)
+            return None

sycommon/llm/sy_langfuse.py

@@ -0,0 +1,103 @@
+import os
+from typing import Tuple, List, Optional, Any, Dict
+from langfuse import Langfuse, get_client
+from sycommon.config.Config import Config, SingletonMeta
+from sycommon.logging.kafka_log import SYLogger
+from langfuse.langchain import CallbackHandler
+from sycommon.tools.env import get_env_var
+from sycommon.tools.merge_headers import get_header_value
+
+
+class LangfuseInitializer(metaclass=SingletonMeta):
+    """
+    Langfuse 初始化管理器
+    """
+
+    def __init__(self):
+        self._langfuse_client: Optional[Langfuse] = None
+        self._base_callbacks: List[Any] = []
+
+        # 执行初始化
+        self._initialize()
+
+    def _initialize(self):
+        """执行实际的配置读取和组件创建"""
+        try:
+            config_dict = Config().config
+
+            server_name = config_dict.get('Name', '')
+            langfuse_configs = config_dict.get('LangfuseConfig', [])
+            environment = config_dict.get('Nacos', {}).get('namespaceId', '')
+
+            # 3. 查找匹配的配置项
+            target_config = next(
+                (item for item in langfuse_configs if item.get(
+                    'name') == server_name), None
+            )
+
+            # 4. 如果启用且配置存在，初始化 Langfuse
+            if target_config and target_config.get('enable', False):
+                # 设置环境变量
+                os.environ["LANGFUSE_SECRET_KEY"] = target_config.get(
+                    'secretKey', '')
+                os.environ["LANGFUSE_PUBLIC_KEY"] = target_config.get(
+                    'publicKey', '')
+                os.environ["LANGFUSE_BASE_URL"] = target_config.get(
+                    'baseUrl', '')
+                os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = environment
+                os.environ["OTEL_SERVICE_NAME"] = server_name
+
+                self._langfuse_client = get_client()
+
+                langfuse_handler = CallbackHandler()
+                self._base_callbacks.append(langfuse_handler)
+
+                SYLogger.info(f"Langfuse 初始化成功 [Service: {server_name}]")
+            else:
+                SYLogger.info(f"Langfuse 未启用或未找到匹配配置 [Service: {server_name}]")
+
+        except Exception as e:
+            SYLogger.error(f"Langfuse 初始化异常: {str(e)}", exc_info=True)
+
+    @property
+    def callbacks(self) -> List[Any]:
+        """获取回调列表"""
+        return self._base_callbacks
+
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        """动态生成包含 langfuse_session_id 和 langfuse_user_id 的 metadata"""
+        trace_id = SYLogger.get_trace_id()
+        userid = get_header_value(
+            SYLogger.get_headers(), "x-userid-header")
+        syVersion = get_header_value(
+            SYLogger.get_headers(), "s-y-version")
+        user_id = userid or syVersion or get_env_var('VERSION')
+        metadata_config = {
+            "langfuse_session_id": trace_id,
+            "langfuse_user_id": user_id,
+        }
+
+        return metadata_config
+
+    @property
+    def client(self) -> Optional[Langfuse]:
+        """获取 Langfuse 原生客户端实例"""
+        return self._langfuse_client
+
+    @property
+    def config(self) -> Dict[str, Any]:
+        return {
+            "callbacks": self.callbacks,
+            "metadata": self.metadata,
+        }
+
+    def get_components(self) -> Tuple[List[Any], Optional[Langfuse]]:
+        """获取 Langfuse 组件"""
+        return list(self._base_callbacks), self._langfuse_client
+
+    @staticmethod
+    def get() -> Tuple[List[Any], Optional[Langfuse]]:
+        """一句话获取组件"""
+        initializer = LangfuseInitializer()
+        return initializer.get_components()

sycommon/llm/usage_token.py

@@ -0,0 +1,117 @@
+from typing import Type, List, Optional, Callable
+from langfuse import Langfuse
+from langchain_core.language_models import BaseChatModel
+from langchain_core.runnables import Runnable, RunnableLambda
+from langchain_core.output_parsers import PydanticOutputParser
+from langchain_core.messages import BaseMessage, HumanMessage
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from pydantic import BaseModel, ValidationError, Field
+from sycommon.llm.struct_token import StructuredRunnableWithToken
+
+
+class LLMWithAutoTokenUsage(BaseChatModel):
+    """自动为结构化调用返回token_usage的LLM包装类"""
+    llm: BaseChatModel = Field(default=None)
+    langfuse: Optional[Langfuse] = Field(default=None, exclude=True)
+
+    def __init__(self, llm: BaseChatModel, langfuse: Langfuse, **kwargs):
+        super().__init__(llm=llm, langfuse=langfuse, **kwargs)
+
+    def with_structured_output(
+        self,
+        output_model: Type[BaseModel],
+        max_retries: int = 3,
+        is_extract: bool = False,
+        override_prompt: ChatPromptTemplate = None,
+        custom_processors: Optional[List[Callable[[str], str]]] = None,
+        custom_parser: Optional[Callable[[str], BaseModel]] = None
+    ) -> Runnable:
+        """返回支持自动统计Token的结构化Runnable"""
+        parser = PydanticOutputParser(pydantic_object=output_model)
+
+        # 提示词模板
+        accuracy_instructions = """
+        字段值的抽取准确率（0~1之间），评分规则：
+        1.0（完全准确）：直接从原文提取，无需任何加工，且格式与原文完全一致
+        0.9（轻微处理）：数据来源明确，但需进行格式标准化或冗余信息剔除（不改变原始数值）
+        0.8（有限推断）：数据需通过上下文关联或简单计算得出，仍有明确依据
+        0.8以下（不可靠）：数据需大量推测、存在歧义或来源不明，处理方式：直接忽略该数据，设置为None
+        """
+
+        if is_extract:
+            prompt = ChatPromptTemplate.from_messages([
+                MessagesPlaceholder(variable_name="messages"),
+                HumanMessage(content=f"""
+                请提取信息并遵循以下规则：
+                1. 准确率要求：{accuracy_instructions.strip()}
+                2. 输出格式：{parser.get_format_instructions()}
+                """)
+            ])
+        else:
+            prompt = override_prompt or ChatPromptTemplate.from_messages([
+                MessagesPlaceholder(variable_name="messages"),
+                HumanMessage(content=f"""
+                输出格式：{parser.get_format_instructions()}
+                """)
+            ])
+
+        # 文本处理函数
+        def extract_response_content(response: BaseMessage) -> str:
+            try:
+                return response.content
+            except Exception as e:
+                raise ValueError(f"提取响应内容失败：{str(e)}") from e
+
+        def strip_code_block_markers(content: str) -> str:
+            try:
+                return content.strip("```json").strip("```").strip()
+            except Exception as e:
+                raise ValueError(f"移除代码块标记失败：{str(e)}") from e
+
+        def normalize_in_json(content: str) -> str:
+            try:
+                return content.replace("None", "null").replace("none", "null").replace("NONE", "null").replace("''", '""')
+            except Exception as e:
+                raise ValueError(f"JSON格式化失败：{str(e)}") from e
+
+        def default_parse_to_pydantic(content: str) -> BaseModel:
+            try:
+                return parser.parse(content)
+            except (ValidationError, ValueError) as e:
+                raise ValueError(f"解析结构化结果失败：{str(e)}") from e
+
+        # ========== 构建处理链 ==========
+        base_chain = prompt | self.llm | RunnableLambda(
+            extract_response_content)
+
+        # 文本处理链
+        process_runnables = custom_processors or [
+            RunnableLambda(strip_code_block_markers),
+            RunnableLambda(normalize_in_json)
+        ]
+        process_chain = base_chain
+        for runnable in process_runnables:
+            process_chain = process_chain | runnable
+
+        # 解析链
+        parse_chain = process_chain | RunnableLambda(
+            custom_parser or default_parse_to_pydantic)
+
+        # 重试链
+        retry_chain = parse_chain.with_retry(
+            retry_if_exception_type=(ValidationError, ValueError),
+            stop_after_attempt=max_retries,
+            wait_exponential_jitter=True,
+            exponential_jitter_params={
+                "initial": 0.1, "max": 3.0, "exp_base": 2.0, "jitter": 1.0}
+        )
+
+        return StructuredRunnableWithToken(retry_chain, self.langfuse)
+
+    # ========== 实现BaseChatModel抽象方法 ==========
+    def _generate(self, messages, stop=None, run_manager=None, ** kwargs):
+        return self.llm._generate(messages, stop=stop, run_manager=run_manager, ** kwargs)
+
+    @property
+    def _llm_type(self) -> str:
+        return self.llm._llm_type

sycommon/logging/async_sql_logger.py

@@ -0,0 +1,65 @@
+from sqlalchemy import event
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sycommon.logging.kafka_log import SYLogger
+import time
+from datetime import datetime
+from decimal import Decimal
+
+
+class AsyncSQLTraceLogger:
+    @staticmethod
+    def setup_sql_logging(engine):
+        """
+        为 SQLAlchemy 异步引擎注册事件监听器
+        注意：必须监听 engine.sync_engine，而不能直接监听 AsyncEngine
+        """
+        def serialize_params(params):
+            """处理特殊类型参数的序列化"""
+            if isinstance(params, (list, tuple)):
+                return [serialize_params(p) for p in params]
+            elif isinstance(params, dict):
+                return {k: serialize_params(v) for k, v in params.items()}
+            elif isinstance(params, datetime):
+                return params.isoformat()
+            elif isinstance(params, Decimal):
+                return float(params)
+            else:
+                return params
+
+        # ========== 核心修改 ==========
+        # 必须通过 engine.sync_engine 来获取底层的同步引擎进行监听
+        target = engine.sync_engine
+
+        @event.listens_for(target, "after_cursor_execute")
+        def after_cursor_execute(
+            conn, cursor, statement, parameters, context, executemany
+        ):
+            try:
+                # 从连接选项中获取开始时间
+                # conn 在这里是同步连接对象
+                start_time = conn.info.get('_start_time') or \
+                    conn._execution_options.get("_start_time", time.time())
+
+                execution_time = (time.time() - start_time) * 1000
+
+                sql_log = {
+                    "type": "SQL",
+                    "statement": statement,
+                    "parameters": serialize_params(parameters),
+                    "execution_time_ms": round(execution_time, 2),
+                }
+
+                # 注意：SYLogger.info 必须是线程安全的或非阻塞的，否则可能影响异步性能
+                SYLogger.info(f"SQL执行: {sql_log}")
+            except Exception as e:
+                SYLogger.error(f"SQL日志处理失败: {str(e)}")
+
+        @event.listens_for(target, "before_cursor_execute")
+        def before_cursor_execute(
+            conn, cursor, statement, parameters, context, executemany
+        ):
+            try:
+                # 记录开始时间到 execution_options
+                conn = conn.execution_options(_start_time=time.time())
+            except Exception as e:
+                SYLogger.error(f"SQL开始时间记录失败: {str(e)}")