> ## Documentation Index
> Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义接口

> 为非 OpenAI 兼容的提供商实现 LLM_Interface

# 自定义接口

SimpleLLMFunc 内置了 `OpenAICompatible` 和 `OpenAIResponsesCompatible`。对于不遵循这两种协议的提供商，可以直接实现 `LLM_Interface`。

## 抽象基类

```python theme={null}
from SimpleLLMFunc.interface import LLM_Interface, APIKeyPool

class LLM_Interface(ABC):
    def __init__(self, api_key_pool, model_name, base_url=None, context_window=200_000):
        self.api_key_pool = api_key_pool
        self.model_name = model_name
        self.base_url = base_url
        self.context_window = context_window

    @abstractmethod
    async def chat(self, *, trace_id, stream=False, messages, timeout=None, **kwargs):
        """Non-streaming call. Returns ChatCompletion-like object."""
        ...

    @abstractmethod
    async def chat_stream(self, *, trace_id, stream=True, messages, timeout=None, **kwargs):
        """Streaming call. Returns AsyncGenerator of ChatCompletionChunk-like objects."""
        ...
```

## 最小实现

```python theme={null}
from SimpleLLMFunc.interface import LLM_Interface, APIKeyPool


class MyProviderInterface(LLM_Interface):
    def __init__(self, api_key_pool: APIKeyPool, model_name: str, base_url: str):
        super().__init__(api_key_pool, model_name, base_url)
        # 在此初始化你的客户端

    async def chat(self, *, trace_id, stream=False, messages, timeout=None, **kwargs):
        api_key = self.api_key_pool.get_key()
        # 发起 API 调用
        response = await my_client.complete(
            model=self.model_name,
            messages=messages,
            api_key=api_key,
        )
        # 返回 ChatCompletion 兼容的格式
        return self._to_chat_completion(response)

    async def chat_stream(self, *, trace_id, stream=True, messages, timeout=None, **kwargs):
        api_key = self.api_key_pool.get_key()
        async for chunk in my_client.stream(
            model=self.model_name,
            messages=messages,
            api_key=api_key,
        ):
            yield self._to_chunk(chunk)
```

## 响应格式要求

框架期望响应与 OpenAI 的类型兼容：

### 非流式（`chat`）

必须返回包含以下字段的对象：

* `.choices[0].message.content` —— 文本响应
* `.choices[0].message.tool_calls` —— 工具调用列表（可选）
* `.usage.prompt_tokens`、`.usage.completion_tokens` —— token 计数

### 流式（`chat_stream`）

必须 yield 包含以下字段的对象：

* `.choices[0].delta.content` —— 文本增量（可能为 None）
* `.choices[0].delta.tool_calls` —— 工具调用增量（可选）
* `.choices[0].finish_reason` —— "stop"、"tool\_calls" 等（在最终 chunk 中）

## 工具调用格式

如果你的提供商支持工具调用，工具调用必须遵循以下格式：

```python theme={null}
{
    "id": "call_abc123",
    "type": "function",
    "function": {
        "name": "tool_name",
        "arguments": '{"param": "value"}'  # JSON 字符串
    }
}
```

## 使用你的接口

```python theme={null}
llm = MyProviderInterface(
    api_key_pool=APIKeyPool(api_keys=["key1"], provider_id="my-provider"),
    model_name="my-model",
    base_url="https://api.myprovider.com/v1",
)

@llm_function(llm_interface=llm)
async def my_function(text: str) -> str:
    """Works with any LLM_Interface implementation."""
    pass
```

## OpenAIResponsesCompatible

对于实现了 OpenAI Responses API（非标准 Chat Completions API）的提供商：

```python theme={null}
from SimpleLLMFunc import OpenAIResponsesCompatible, APIKeyPool

llm = OpenAIResponsesCompatible(
    api_key_pool=APIKeyPool(api_keys=["sk-..."], provider_id="openai-responses"),
    model_name="gpt-4o",
    base_url="https://api.openai.com/v1",
)
```

Responses 适配器的功能：

* 将系统提示词映射到 Responses 的 `instructions` 字段
* 处理 Responses 特有的流式格式
* 支持 `reasoning={...}` kwargs 来控制推理力度
* 所有协议格式差异都封装在适配器内部——你的装饰器代码无需变动

→ [API 参考：接口](/zh/api/interfaces)