# fetchModelList 模块

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

## 安装依赖

```bash
pip install oiiai-lib
# or
uv pip install oiiai-lib
# In your project
uv add oiiai-lib
```

## 基类

### 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)` | 处理缺失的环境变量 | `[]` |

## 内置实现

### 使用方式

所有 Fetcher 都遵循统一的接口模式：

```python
from oiiai import Fetch<Provider>

# 需要 API Key 的提供商（以 FetchNova 为例）
fetcher = FetchNova(api_key="your-api-key")  # 或从环境变量读取
models = fetcher.fetch_models()

# 不需要 API Key 的提供商（以 FetchZhipu 为例）
fetcher = FetchZhipu()
models = fetcher.fetch_models()
```

### 可用提供商

| 类名 | 提供商 | API Key | 环境变量 | 特殊方法 |
|------|--------|---------|----------|----------|
| `FetchZhipu` | 智谱 AI | 不需要 | - | - |
| `FetchModelScope` | ModelScope | 不需要 | - | - |
| `FetchIFlow` | IFlow | 不需要 | - | - |
| `FetchOpenRouter` | OpenRouter | 可选 | `OPENROUTER_API_KEY` | - |
| `FetchSiliconFlow` | SiliconFlow | 需要 | `SILICONFLOW_API_KEY` | - |
| `FetchNova` | Amazon Nova | 需要 | `NOVA_API_KEY` | `fetch_models_raw()` |

### 详细示例

#### 需要 API Key 的提供商

```python
from oiiai import FetchNova

# 方式一：直接传入 API Key
fetcher = FetchNova(api_key="your-api-key")

# 方式二：从环境变量读取（设置 NOVA_API_KEY）
fetcher = FetchNova()

# 获取模型列表
models = fetcher.fetch_models()
print(models)  # ['amazon.nova-pro-v1:0', 'amazon.nova-lite-v1:0', ...]

# Nova 特有：获取原始 API 响应
raw_response = fetcher.fetch_models_raw()
```

#### 不需要 API Key 的提供商

```python
from oiiai import FetchZhipu

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

### fetch_models_raw()（仅 FetchNova）

返回 Nova API 的原始 JSON 响应，包含完整的模型元数据：

```python
{
    "object": "list",
    "data": [
        {
            "created": 1234567890,
            "description": "Model description",
            "display name": "Human-readable name",
            "id": "model-id",
            "owned_by": "amazon",
            "type": "model"
        },
        ...
    ]
}
```

## 扩展

实现自定义获取器只需继承 `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()  # 如果出错，返回 [] 并记录日志
```
