# fetchModelList 模块

获取各 AI 提供商的可用模型列表。

## 安装依赖

```bash
pip install requests
```

## 基类

### FetchBase

所有模型获取器的抽象基类，提供统一的日志记录和错误处理方法。

```python
from oiiai import FetchBase
from typing import List

class MyFetcher(FetchBase):
    @property
    def provider(self) -> str:
        return "my_provider"
    
    def fetch_models(self) -> List[str]:
        try:
            # 实现获取逻辑
            self._log_info("开始获取模型列表")
            return ["model-1", "model-2"]
        except Exception as e:
            return self._handle_http_error(e)
```

#### 日志方法

| 方法 | 说明 |
|------|------|
| `_log_error(message, exc_info=False)` | 记录 ERROR 级别日志 |
| `_log_warning(message)` | 记录 WARNING 级别日志 |
| `_log_info(message)` | 记录 INFO 级别日志 |
| `_log_debug(message)` | 记录 DEBUG 级别日志 |

#### 错误处理方法

| 方法 | 说明 | 返回值 |
|------|------|--------|
| `_handle_http_error(error)` | 处理 HTTP 请求错误 | `[]` |
| `_handle_unexpected_format(data)` | 处理意外的 API 响应格式 | `[]` |
| `_handle_missing_env_var(var_name)` | 处理缺失的环境变量 | `[]` |

## 内置实现

### FetchOpenRouter

从 OpenRouter API 获取模型列表。

```python
from oiiai import FetchOpenRouter

# 使用 API Key（可选，不传则从环境变量 OPENROUTER_API_KEY 获取）
fetcher = FetchOpenRouter(api_key="your-api-key")

# 获取模型列表
models = fetcher.fetch_models()
print(models)  # ['openai/gpt-4o', 'anthropic/claude-3-opus', ...]
```

### FetchZhipu

从智谱 AI 官方文档页面解析模型列表。

```python
from oiiai import FetchZhipu

fetcher = FetchZhipu()
models = fetcher.fetch_models()
print(models)  # ['glm-4-flash', 'glm-4', ...]
```

### FetchModelScope

从 ModelScope API 获取模型列表。

```python
from oiiai import FetchModelScope

fetcher = FetchModelScope()
models = fetcher.fetch_models()
print(models)  # ['deepseek-ai/DeepSeek-R1-0528', 'Qwen/Qwen2.5-72B-Instruct', ...]
```

### FetchSiliconFlow

从 SiliconFlow API 获取模型列表。需要设置环境变量 `SILICONFLOW_API_KEY`。

```python
from oiiai import FetchSiliconFlow

fetcher = FetchSiliconFlow()
models = fetcher.fetch_models()
print(models)  # ['deepseek-ai/DeepSeek-R1', 'Qwen/Qwen2.5-72B-Instruct', ...]
```

### FetchIFlow

从 IFlow 平台获取模型列表。

```python
from oiiai import FetchIFlow

fetcher = FetchIFlow()
models = fetcher.fetch_models()
print(models)  # ['qwen3-max', 'deepseek-r1', 'kimi-k2', ...]
```

## 扩展

实现自定义获取器只需继承 `FetchBase` 并实现 `provider` 属性和 `fetch_models()` 方法。

## 日志配置

fetchModelList 模块提供统一的日志记录系统，支持 JSON 格式输出和异步日志。

### configure_logging

配置全局日志设置。

```python
import logging
from oiiai import configure_logging

# 基本配置
configure_logging(level=logging.DEBUG)

# 完整配置
configure_logging(
    level=logging.WARNING,    # 日志级别（默认: WARNING）
    handler=None,             # 自定义 Handler（默认: NullHandler）
    use_json=True,            # 是否使用 JSON 格式（默认: True）
    async_enabled=False,      # 是否启用异步日志（默认: False）
)
```

### shutdown_logging

关闭异步日志并清理资源。在程序退出前调用以确保所有日志写入完成。

```python
from oiiai import shutdown_logging

shutdown_logging()
```

### 自定义 Handler

```python
import logging
from oiiai import configure_logging

# 输出到文件
file_handler = logging.FileHandler("oiiai.log")
configure_logging(level=logging.INFO, handler=file_handler)

# 输出到控制台
stream_handler = logging.StreamHandler()
configure_logging(level=logging.DEBUG, handler=stream_handler)
```

### 异步日志

在高并发场景下启用异步日志避免阻塞：

```python
from oiiai import configure_logging, shutdown_logging

configure_logging(level=logging.INFO, async_enabled=True)

# 程序退出前务必调用
shutdown_logging()
```

### JSON 日志格式

| 字段 | 类型 | 说明 |
|------|------|------|
| timestamp | string | ISO 8601 格式时间戳 |
| level | string | 日志级别 (DEBUG/INFO/WARNING/ERROR/CRITICAL) |
| provider | string | Provider 标识符 |
| message | string | 日志消息 |
| module | string | 模块名称 |
| function | string | 函数名称 |
| line | int | 行号 |
| exc_info | string | 异常堆栈信息（可选） |

### 错误处理

所有 provider 在遇到错误时会自动记录日志并返回空列表，不会抛出异常：

- HTTP 请求失败 → ERROR 级别日志
- API 响应格式异常 → WARNING 级别日志
- 环境变量缺失 → WARNING 级别日志

```python
from oiiai import FetchSiliconFlow, configure_logging
import logging

# 启用日志查看错误信息
configure_logging(level=logging.WARNING, handler=logging.StreamHandler())

fetcher = FetchSiliconFlow()
models = fetcher.fetch_models()  # 如果出错，返回 [] 并记录日志
```
