springbootAI 1.8.0__py3-none-any.whl

spring/ai/resilience.py

@@ -0,0 +1,258 @@
+"""
+AI 调用韧性 - 复用框架 spring.retry 的 @Retryable 机制 + 复用 spring.aop 的 CircuitBreaker 状态机。
+
+为 LLM HTTP 调用提供：
+1. 重试：复用 spring.retry.retry_decorator.retry() 便捷装饰器，对网络瞬态错误重试
+2. 熔断：CLOSED/OPEN/HALF_OPEN 状态机，复用框架 Redis 持久化电路状态（同 spring.aop.comprehensive_aop.circuit_breaker_decorator），
+   Redis 不可用时降级本地内存。跨实例共享熔断状态，多副本一致性。
+"""
+import functools
+import json
+import logging
+import threading
+import time
+from typing import Any, Callable, Dict, Optional, Tuple, Type
+
+logger = logging.getLogger("Spring.AI.Resilience")
+
+# 复用框架重试基础设施
+try:
+    from spring.retry.retry_decorator import retry as _retry_decorator
+    from spring.retry.retry_annotations import Backoff
+    _RETRY_AVAILABLE = True
+except ImportError:
+    _RETRY_AVAILABLE = False
+
+
+class CircuitState:
+    CLOSED = "CLOSED"
+    OPEN = "OPEN"
+    HALF_OPEN = "HALF_OPEN"
+
+
+class AICircuitBreaker:
+    """
+    熔断器 - 复用框架 spring.aop.comprehensive_aop 的 CircuitBreaker 状态机策略。
+
+    状态流转：
+        CLOSED --失败数>=threshold--> OPEN
+        OPEN   --经过recovery_timeout--> HALF_OPEN
+        HALF_OPEN --成功--> CLOSED
+        HALF_OPEN --失败--> OPEN
+
+    状态存储策略（与框架 circuit_breaker_decorator 一致）：
+    - 优先用 Redis hash 持久化（`circuit_breaker:ai:{name}`），跨实例共享
+    - Redis 不可用时降级本地内存
+    """
+
+    _local_cache: Dict[str, dict] = {}  # 类级本地缓存的回退
+
+    def __init__(self, failure_threshold: int = 5,
+                 recovery_timeout: float = 30.0,
+                 fallback: Optional[Callable] = None,
+                 name: str = "default",
+                 redis_client=None):
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout = recovery_timeout
+        self.fallback = fallback
+        self.name = name
+        self._redis_client = redis_client
+        self._redis_key = f"circuit_breaker:ai:{name}"
+        self._lock = threading.Lock()
+        # 本地状态（读透 Redis 缓存）
+        self._state = CircuitState.CLOSED
+        self._failures = 0
+        self._last_failure_time = 0.0
+
+    def _redis_available(self) -> bool:
+        """Redis 是否可用"""
+        if self._redis_client is None:
+            return False
+        try:
+            rc = (self._redis_client.get_client()
+                  if hasattr(self._redis_client, "get_client")
+                  else self._redis_client)
+            return rc is not None
+        except Exception:
+            return False
+
+    def _raw_redis(self):
+        """获取原生 Redis 客户端"""
+        if self._redis_client is None:
+            return None
+        return (self._redis_client.get_client()
+                if hasattr(self._redis_client, "get_client")
+                else self._redis_client)
+
+    def _sync_from_redis(self):
+        """从 Redis 同步状态到本地（读取透）"""
+        r = self._raw_redis()
+        if r is None:
+            return
+        try:
+            state_data = r.hgetall(self._redis_key)
+            if state_data:
+                state = (state_data.get("state", b"CLOSED")
+                         if isinstance(state_data, dict) else {})
+                if isinstance(state, bytes):
+                    state = state.decode()
+                self._state = state if isinstance(state, str) else "CLOSED"
+                self._failures = int(state_data.get("failures", 0) if isinstance(
+                    state_data.get("failures"), (int, bytes, str)) else 0)
+                lf = state_data.get("last_failure_time", 0)
+                self._last_failure_time = float(lf) if isinstance(lf, (int, float, bytes, str)) else 0.0
+        except Exception:
+            # Redis 失败，保持本地状态
+            pass
+
+    def _sync_to_redis(self):
+        """将本地状态同步到 Redis"""
+        r = self._raw_redis()
+        if r is None:
+            return
+        try:
+            r.hset(self._redis_key, mapping={
+                "state": self._state,
+                "failures": str(self._failures),
+                "last_failure_time": str(self._last_failure_time),
+            })
+        except Exception:
+            pass
+
+    @property
+    def state(self) -> str:
+        with self._lock:
+            self._refresh_state()
+            return self._state
+
+    def _refresh_state(self):
+        # 先从 Redis 同步（如果可用）
+        if self._redis_available():
+            self._sync_from_redis()
+        if (self._state == CircuitState.OPEN and
+                time.time() - self._last_failure_time > self.recovery_timeout):
+            self._state = CircuitState.HALF_OPEN
+            logger.info("AI 熔断器[%s] 进入 HALF_OPEN，尝试放行探测请求", self.name)
+            if self._redis_available():
+                self._sync_to_redis()
+
+    def allow(self) -> bool:
+        """是否放行请求"""
+        with self._lock:
+            self._refresh_state()
+            return self._state in (CircuitState.CLOSED, CircuitState.HALF_OPEN)
+
+    def record_success(self):
+        with self._lock:
+            if self._state == CircuitState.HALF_OPEN:
+                logger.info("AI 熔断器[%s] HALF_OPEN -> CLOSED（探测成功）", self.name)
+            self._state = CircuitState.CLOSED
+            self._failures = 0
+            if self._redis_available():
+                self._sync_to_redis()
+
+    def record_failure(self):
+        with self._lock:
+            self._failures += 1
+            self._last_failure_time = time.time()
+            if self._state == CircuitState.HALF_OPEN:
+                self._state = CircuitState.OPEN
+                logger.warning("AI 熔断器[%s] HALF_OPEN -> OPEN（探测失败）", self.name)
+            elif self._failures >= self.failure_threshold:
+                self._state = CircuitState.OPEN
+                logger.warning("AI 熔断器[%s] CLOSED -> OPEN（失败数=%d）",
+                               self.name, self._failures)
+            if self._redis_available():
+                self._sync_to_redis()
+
+    def call(self, func: Callable, *args, **kwargs):
+        """经熔断器执行函数"""
+        from spring.ai.observability import ai_metrics
+        _provider = kwargs.pop("_cb_provider", "unknown")
+        if not self.allow():
+            ai_metrics.record_circuit_state(_provider, self._state)
+            if self.fallback:
+                return self.fallback(*args, **kwargs)
+            raise CircuitOpenError(
+                f"AI 熔断器[{self.name}] 处于 {self._state} 状态，拒绝请求（失败数={self._failures}）")
+        try:
+            result = func(*args, **kwargs)
+            self.record_success()
+            ai_metrics.record_circuit_state(_provider, CircuitState.CLOSED)
+            return result
+        except Exception as exc:
+            # 调用方自行决定哪些异常计入失败
+            if isinstance(exc, TransientError):
+                self.record_failure()
+            ai_metrics.record_circuit_state(_provider, self._state)
+            raise
+
+
+class TransientError(Exception):
+    """瞬态错误（网络抖动/超时/429），应触发重试与熔断计数"""
+
+
+class CircuitOpenError(Exception):
+    """熔断器开启"""
+
+
+def resilient_call(func: Callable,
+                   max_retries: int = 3,
+                   retry_delay_ms: int = 500,
+                   retry_exceptions: Tuple[Type[Exception], ...] = (Exception,),
+                   circuit_breaker: Optional[AICircuitBreaker] = None,
+                   count_as_failure_exc: Tuple[Type[Exception], ...] = (Exception,),
+                   provider: str = "unknown",
+                   ) -> Callable:
+    """
+    为 LLM HTTP 调用注入重试 + 熔断。
+
+    - 重试：复用 spring.retry.retry_decorator.retry（不可用时降级为简单循环）
+    - 熔断：经 AICircuitBreaker.call 放行，count_as_failure_exc 内异常计入失败
+    - provider：透传给熔断器指标，确保 ai_circuit_breaker_state label 可区分
+    """
+    count_as_failure_exc = count_as_failure_exc or (Exception,)
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        # 1. 构造带重试的核心函数
+        if _RETRY_AVAILABLE:
+            retried = _retry_decorator(
+                max_retries=max_retries, delay=retry_delay_ms,
+                exceptions=retry_exceptions,
+            )(func)
+        else:
+            retried = func
+
+        # 2. 把 provider 注入 kwargs 让 AICircuitBreaker 可读到
+        #    调用实际函数前 pop 掉，避免透传
+        kwargs["_cb_provider"] = provider
+
+        # 3. 无熔断器 → 直接重试调用
+        if circuit_breaker is None:
+            kwargs.pop("_cb_provider", None)
+            return retried(*args, **kwargs)
+
+        # 4. 有熔断器 → 经熔断放行，失败计入熔断
+        if not circuit_breaker.allow():
+            from spring.ai.observability import ai_metrics
+            kwargs.pop("_cb_provider", None)
+            ai_metrics.record_circuit_state(provider, circuit_breaker.state)
+            if circuit_breaker.fallback:
+                return circuit_breaker.fallback(*args, **kwargs)
+            raise CircuitOpenError("AI 熔断器处于 OPEN 状态，拒绝请求")
+
+        try:
+            kwargs.pop("_cb_provider", None)
+            result = retried(*args, **kwargs)
+            circuit_breaker.record_success()
+            from spring.ai.observability import ai_metrics
+            ai_metrics.record_circuit_state(provider, CircuitState.CLOSED)
+            return result
+        except count_as_failure_exc as exc:
+            circuit_breaker.record_failure()
+            from spring.ai.observability import ai_metrics
+            ai_metrics.record_circuit_state(provider, circuit_breaker.state)
+            raise
+
+    return wrapper

spring/ai/tools.py

@@ -0,0 +1,106 @@
+"""
+工具/函数调用注册表 - 从 Python 函数签名自动生成 tool schema，执行模型发起的工具调用。
+
+不依赖 OpenAI function-calling 协议细节，生成通用 schema，由 Provider 适配层转换为
+各模型要求的格式。
+"""
+import inspect
+import json
+from typing import Any, Callable, Dict, List, Optional
+
+
+_PY_TO_JSON_TYPE = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+}
+
+
+class ToolDefinition:
+    """工具定义"""
+
+    def __init__(self, name: str, description: str, func: Callable,
+                 parameters: Dict[str, Any], return_type: str = "string"):
+        self.name = name
+        self.description = description
+        self.func = func
+        self.parameters = parameters
+        self.return_type = return_type
+
+    def to_schema(self) -> Dict[str, Any]:
+        """生成 OpenAI 风格的 function schema"""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": {
+                    "type": "object",
+                    "properties": self.parameters,
+                    "required": [
+                        p for p, m in self.parameters.items()
+                        if m.get("__required", True)
+                    ],
+                },
+            },
+        }
+
+
+class ToolRegistry:
+    """工具注册表 - 管理所有可被 LLM 调用的工具"""
+
+    def __init__(self):
+        self._tools: Dict[str, ToolDefinition] = {}
+
+    def register(self, name: str, func: Callable,
+                 description: str = "", return_description: str = "") -> ToolDefinition:
+        """注册工具，从签名自动推断参数 schema"""
+        sig = inspect.signature(func)
+        properties: Dict[str, Any] = {}
+        for pname, param in sig.parameters.items():
+            if pname in ("self", "cls"):
+                continue
+            py_type = param.annotation if param.annotation is not inspect.Parameter.empty else str
+            json_type = _PY_TO_JSON_TYPE.get(py_type, "string")
+            required = param.default is inspect.Parameter.empty
+            prop = {"type": json_type, "__required": required}
+            properties[pname] = prop
+
+        # 返回类型
+        ret_type = "string"
+        if sig.return_annotation is not inspect.Signature.empty:
+            ret_type = _PY_TO_JSON_TYPE.get(sig.return_annotation, "string")
+
+        desc = description or (func.__doc__ or "").strip().split("\n")[0]
+        tool = ToolDefinition(name=name, description=desc, func=func,
+                              parameters=properties, return_type=ret_type)
+        self._tools[name] = tool
+        return tool
+
+    def get(self, name: str) -> Optional[ToolDefinition]:
+        return self._tools.get(name)
+
+    def names(self) -> List[str]:
+        return list(self._tools.keys())
+
+    def schemas(self) -> List[Dict[str, Any]]:
+        """返回所有工具的 schema（供 Provider 注入模型）"""
+        return [t.to_schema() for t in self._tools.values()]
+
+    def execute(self, name: str, arguments: Dict[str, Any]) -> Any:
+        """按名称执行工具"""
+        tool = self._tools.get(name)
+        if tool is None:
+            raise KeyError(f"工具未注册: {name}")
+        if isinstance(arguments, str):
+            arguments = json.loads(arguments)
+        return tool.func(**arguments)
+
+    def clear(self) -> None:
+        self._tools.clear()
+
+    def __len__(self) -> int:
+        return len(self._tools)

spring/ai/vectorstore.py

@@ -0,0 +1,303 @@
+"""
+向量存储抽象与内存实现 - 为 RAG 提供文档向量的存储与相似度检索。
+
+生产环境可替换为 PGVector / Milvus / Chroma 等实现（实现同一 VectorStore 接口）。
+"""
+import json
+import math
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Document:
+    """向量文档"""
+    id: str
+    content: str
+    embedding: List[float] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SearchRequest:
+    """检索请求"""
+    query: str
+    embedding: Optional[List[float]] = None
+    top_k: int = 4
+    similarity_threshold: float = 0.0
+    filter_expression: Optional[str] = None
+
+
+class VectorStore(ABC):
+    """向量存储抽象"""
+
+    @abstractmethod
+    def add(self, documents: List[Document]) -> None:
+        """写入文档（需已包含 embedding）"""
+
+    @abstractmethod
+    def similarity_search(self, request: SearchRequest) -> List[Document]:
+        """相似度检索"""
+
+
+def cosine_similarity(a: List[float], b: List[float]) -> float:
+    """余弦相似度"""
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0 or nb == 0:
+        return 0.0
+    return dot / (na * nb)
+
+
+class SimpleInMemoryVectorStore(VectorStore):
+    """内存向量存储 - 开发/测试用，余弦相似度"""
+
+    def __init__(self, embedding_model=None):
+        self._docs: List[Document] = []
+        self._embedding_model = embedding_model
+
+    def add(self, documents: List[Document]) -> None:
+        for doc in documents:
+            if not doc.embedding and self._embedding_model and doc.content:
+                doc.embedding = self._embedding_model.embed_one(doc.content)
+            self._docs.append(doc)
+
+    def add_texts(self, texts: List[str],
+                  metadatas: Optional[List[Dict]] = None) -> None:
+        for i, text in enumerate(texts):
+            meta = metadatas[i] if metadatas and i < len(metadatas) else {}
+            self.add([Document(id=f"doc-{len(self._docs)}", content=text,
+                               metadata=meta)])
+
+    def similarity_search(self, request: SearchRequest) -> List[Document]:
+        emb = request.embedding
+        if emb is None and self._embedding_model and request.query:
+            emb = self._embedding_model.embed_one(request.query)
+        if emb is None:
+            return []
+
+        scored = []
+        for doc in self._docs:
+            if not doc.embedding:
+                continue
+            score = cosine_similarity(emb, doc.embedding)
+            if score >= request.similarity_threshold:
+                scored.append((score, doc))
+        scored.sort(key=lambda x: x[0], reverse=True)
+        return [d for _, d in scored[:request.top_k]]
+
+    def count(self) -> int:
+        return len(self._docs)
+
+    def clear(self) -> None:
+        self._docs.clear()
+
+
+class LangChainVectorStore(VectorStore):
+    """
+    LangChain 向量存储适配器 - 包装 langchain 生态的 VectorStore（FAISS/Chroma 等）。
+
+    设计原则：能用 LangChain 就用 LangChain（不做重复造轮子）。本类不自行实现
+    向量索引与检索，而是包装一个外部 langchain 向量存储实例（须提供
+    add_texts / similarity_search_by_vector），把框架统一的 VectorStore 接口
+    映射到 langchain 的成熟实现。需要先安装对应 langchain 向量库（如
+    langchain_community.vectorstores.FAISS / langchain_chroma）并自行构建实例传入。
+    """
+
+    def __init__(self, langchain_store=None, embedding_model=None):
+        self._store = langchain_store
+        self._embedding_model = embedding_model
+
+    def add(self, documents: List[Document]) -> None:
+        if self._store is None:
+            return
+        self._store.add_texts(
+            [d.content for d in documents],
+            metadatas=[d.metadata for d in documents],
+        )
+
+    def add_texts(self, texts: List[str],
+                  metadatas: Optional[List[Dict]] = None) -> None:
+        if self._store is None:
+            return
+        self._store.add_texts(texts, metadatas=metadatas or [{}] * len(texts))
+
+    def similarity_search(self, request: SearchRequest) -> List[Document]:
+        if self._store is None:
+            return []
+        emb = request.embedding
+        if emb is None and self._embedding_model and request.query:
+            emb = self._embedding_model.embed_one(request.query)
+        if emb is None:
+            return []
+        docs = self._store.similarity_search_by_vector(emb, k=request.top_k)
+        result: List[Document] = []
+        for i, d in enumerate(docs):
+            result.append(Document(
+                id=getattr(d, "id", "") or f"langchain-{i}",
+                content=getattr(d, "page_content", str(d)),
+                embedding=emb,
+                metadata=getattr(d, "metadata", {}) or {},
+            ))
+        return result
+
+    def count(self) -> int:
+        return 0 if self._store is None else getattr(self._store, "count", lambda: 0)()
+
+    def clear(self) -> None:
+        if self._store is None:
+            return
+        deleter = getattr(self._store, "delete_collection", None) \
+            or getattr(self._store, "clear", None)
+        if deleter:
+            deleter()
+
+
+def _safe_json_loads(val: Any) -> Optional[dict]:
+    """安全 JSON 解析（兼容 str/bytes/dict）"""
+    if isinstance(val, dict):
+        return val
+    if isinstance(val, bytes):
+        try:
+            val = val.decode(errors="ignore")
+        except Exception:
+            return None
+    if not isinstance(val, str):
+        return None
+    try:
+        return json.loads(val)
+    except (json.JSONDecodeError, TypeError):
+        return None
+
+
+class RedisVectorStore(VectorStore):
+    """
+    Redis 向量存储 - 持久化 + 跨实例共享。
+
+    复用框架 spring.utils.redis_client.RedisClient 封装（与 RedisChatMemory 统一接口）：
+    优先用框架封装的 hash_set/hash_get_all/delete_key（自动 JSON 序列化/反序列化）；
+    若传入原生 redis.Redis 或测试 FakeRedis（仅有 hset/hgetall/delete），自动降级原生接口。
+
+    用 Redis hash 存储文档（id -> JSON{content,embedding,metadata}），
+    检索时拉取全部并在 Python 端计算余弦相似度。
+    适合中小规模（< 10 万文档）多副本部署；更大规模建议接入 RediSearch FTVECTOR。
+
+    max_scan 参数限制单次检索扫描上限，防止数据量过大时 OOM。
+    """
+
+    KEY_PREFIX = "springpy:ai:vectorstore:"
+
+    def __init__(self, redis_client=None, collection: str = "default",
+                 embedding_model=None, max_scan: int = 10000):
+        self._client = redis_client
+        self.collection = collection
+        self._embedding_model = embedding_model
+        self.max_scan = max_scan
+
+    def _key(self) -> str:
+        return f"{self.KEY_PREFIX}{self.collection}"
+
+    @staticmethod
+    def _is_framework_client(client) -> bool:
+        """是否框架 RedisClient 封装（提供 hash_set/hash_get_all）"""
+        return (client is not None and hasattr(client, "hash_set")
+                and hasattr(client, "hash_get_all"))
+
+    @staticmethod
+    def _raw_client(client):
+        """原生 redis 客户端：框架封装取内部 client，否则透传"""
+        return client.get_client() if hasattr(client, "get_client") else client
+
+    def add(self, documents: List[Document]) -> None:
+        if self._client is None:
+            return
+        for doc in documents:
+            if not doc.embedding and self._embedding_model and doc.content:
+                doc.embedding = self._embedding_model.embed_one(doc.content)
+            record = {
+                "id": doc.id, "content": doc.content,
+                "embedding": doc.embedding or [], "metadata": doc.metadata,
+            }
+            if self._is_framework_client(self._client):
+                # 复用框架 RedisClient 封装（自动 JSON 序列化）
+                self._client.hash_set(self._key(), doc.id, record)
+            else:
+                # 降级：原生 redis 接口（兼容 redis.Redis / 测试 FakeRedis）
+                try:
+                    self._raw_client(self._client).hset(
+                        self._key(), doc.id,
+                        json.dumps(record, ensure_ascii=False))
+                except Exception:
+                    pass
+
+    def add_texts(self, texts: List[str],
+                  metadatas: Optional[List[Dict]] = None,
+                  ids: Optional[List[str]] = None) -> None:
+        for i, text in enumerate(texts):
+            doc_id = ids[i] if ids and i < len(ids) else f"doc-{i}"
+            meta = metadatas[i] if metadatas and i < len(metadatas) else {}
+            self.add([Document(id=doc_id, content=text, metadata=meta)])
+
+    def _all_docs(self, max_scan: Optional[int] = None) -> List[Document]:
+        if self._client is None:
+            return []
+        max_scan = max_scan if max_scan is not None else self.max_scan
+        # max_scan <= 0 表示无限制（count() 场景）
+        if self._is_framework_client(self._client):
+            # 框架封装：hash_get_all 已自动 JSON 反序列化
+            raw = self._client.hash_get_all(self._key()) or {}
+        else:
+            try:
+                raw = self._raw_client(self._client).hgetall(self._key()) or {}
+            except Exception:
+                return []
+        docs: List[Document] = []
+        scanned = 0
+        for field, val in raw.items():
+            if max_scan > 0 and scanned >= max_scan:
+                break
+            d = _safe_json_loads(val)
+            if not d:
+                continue
+            docs.append(Document(
+                id=d.get("id", field if isinstance(field, str) else str(field)),
+                content=d.get("content", ""),
+                embedding=d.get("embedding", []),
+                metadata=d.get("metadata", {}),
+            ))
+            scanned += 1
+        return docs
+
+    def similarity_search(self, request: SearchRequest) -> List[Document]:
+        emb = request.embedding
+        if emb is None and self._embedding_model and request.query:
+            emb = self._embedding_model.embed_one(request.query)
+        if emb is None:
+            return []
+        scored = []
+        for doc in self._all_docs():
+            if not doc.embedding:
+                continue
+            score = cosine_similarity(emb, doc.embedding)
+            if score >= request.similarity_threshold:
+                scored.append((score, doc))
+        scored.sort(key=lambda x: x[0], reverse=True)
+        return [d for _, d in scored[:request.top_k]]
+
+    def count(self) -> int:
+        return len(self._all_docs(max_scan=0))  # 0 = 无限制，count 需准确
+
+    def clear(self) -> None:
+        if self._client is None:
+            return
+        if self._is_framework_client(self._client):
+            self._client.delete_key(self._key())
+        else:
+            try:
+                self._raw_client(self._client).delete(self._key())
+            except Exception:
+                pass