BaseLLM API Reference

class lmitf.base_llm.BaseLLM(api_key: str | None = None, base_url: str | None = None)[source]

Bases: object

OpenAI LLM 客户端封装类

提供对 OpenAI Chat Completions API 的简化访问接口，支持文本和 JSON 格式响应。 自动处理环境变量配置，维护调用历史记录。

client

OpenAI 客户端实例

Type:

OpenAI

call_history

API 调用响应的历史记录

Type:

List[Union[str, Dict[str, Any]]]

__init__(api_key: str | None = None, base_url: str | None = None)[source]

初始化 LLM 客户端

Parameters:

  • api_key (str, optional) – OpenAI API 密钥。如果未提供，将从环境变量 OPENAI_API_KEY 读取

  • base_url (str, optional) – API 基础URL。如果未提供，将从环境变量 OPENAI_BASE_URL 读取

call(messages: str | list[dict[str, str]], model: str = 'gpt-4o', response_format: str = 'text', temperature: float | None = None, top_p: float | None = None, frequency_penalty: float | None = None, presence_penalty: float | None = None, seed: int | None = None, max_tokens: int | None = None, stop: list[str] | None = None) → str | dict[str, Any][source]

调用 OpenAI Chat Completions API

Parameters:

  • model (str) – 要使用的模型名称，例如 ‘gpt-4’, ‘gpt-3.5-turbo’

  • messages (str or List[Dict[str, str]]) – 消息列表或单个消息字符串。如果是字符串，将自动转换为用户消息

  • response_format ({'text', 'json'}, default 'text') – 响应格式。’text’ 返回纯文本，’json’ 返回结构化JSON

  • temperature (float, optional) – 控制输出随机性的温度参数，范围 0-2。值越高输出越随机

  • top_p (float, optional) – 核采样参数，范围 0-1。与 temperature 一起控制输出多样性

  • frequency_penalty (float, optional) – 频率惩罚参数，范围 -2 到 2。正值减少重复内容

  • presence_penalty (float, optional) – 存在惩罚参数，范围 -2 到 2。正值鼓励谈论新主题

  • seed (int, optional) – 随机种子，用于获得可重现的输出

  • max_tokens (int, optional) – 生成的最大令牌数

  • stop (List[str], optional) – 停止序列列表，遇到这些序列时停止生成

Returns:

API 响应内容。如果 response_format=’text’ 返回字符串， 如果 response_format=’json’ 返回解析后的字典

Return type:

str or Dict[str, Any]

Raises:

  • ValueError – 当 response_format 不是 ‘text’ 或 ‘json’ 时， 或当请求 JSON 格式但消息中不包含 JSON 指令时

  • json.JSONDecodeError – 当 JSON 响应无法解析时

call_embed(input: str, model: str) → list[float][source]

获取文本的嵌入表示

Parameters:

  • input (str) – 要嵌入的文本输入

  • model (str) – 使用的嵌入模型名称，例如 ‘text-embedding-3-large’

Returns:

嵌入向量列表

Return type:

List[float]

clear_history() → None[source]

清空调用历史

get_last_response() → str | dict[str, Any] | None[source]

获取最后一次调用的响应

print_history() → None[source]

打印调用历史记录

lmitf.base_llm.extract_json(text: str) → dict[str, Any][source]

从字符串中提取第一个 JSON 对象并解析为 Python 字典

支持以下格式： 1. `json ... ` 代码块格式 2. 直接的 { … } JSON 对象格式

Parameters:

text (str) – 包含 JSON 的文本字符串

Returns:

解析后的 JSON 字典

Return type:

Dict[str, Any]

Raises:

json.JSONDecodeError – 当无法找到或解析有效的 JSON 对象时

Examples

>>> text = '```json\n{"name": "test", "value": 123}\n```'
>>> result = extract_json(text)
>>> print(result)
{'name': 'test', 'value': 123}

>>> text = 'Some text {"key": "value"} more text'
>>> result = extract_json(text)
>>> print(result)
{'key': 'value'}

Overview

The BaseLLM class provides a simplified interface for interacting with OpenAI’s Chat Completions API. It handles authentication, request formatting, and response processing automatically.

Class Reference

BaseLLM

class lmitf.base_llm.BaseLLM(api_key: str | None = None, base_url: str | None = None)[source]

Bases: object

OpenAI LLM 客户端封装类

提供对 OpenAI Chat Completions API 的简化访问接口，支持文本和 JSON 格式响应。 自动处理环境变量配置，维护调用历史记录。

client

OpenAI 客户端实例

Type:

OpenAI

call_history

API 调用响应的历史记录

Type:

List[Union[str, Dict[str, Any]]]

__init__(api_key: str | None = None, base_url: str | None = None)[source]

初始化 LLM 客户端

Parameters:

  • api_key (str, optional) – OpenAI API 密钥。如果未提供，将从环境变量 OPENAI_API_KEY 读取

  • base_url (str, optional) – API 基础URL。如果未提供，将从环境变量 OPENAI_BASE_URL 读取

call(messages: str | list[dict[str, str]], model: str = 'gpt-4o', response_format: str = 'text', temperature: float | None = None, top_p: float | None = None, frequency_penalty: float | None = None, presence_penalty: float | None = None, seed: int | None = None, max_tokens: int | None = None, stop: list[str] | None = None) → str | dict[str, Any][source]

调用 OpenAI Chat Completions API

Parameters:

  • model (str) – 要使用的模型名称，例如 ‘gpt-4’, ‘gpt-3.5-turbo’

  • messages (str or List[Dict[str, str]]) – 消息列表或单个消息字符串。如果是字符串，将自动转换为用户消息

  • response_format ({'text', 'json'}, default 'text') – 响应格式。’text’ 返回纯文本，’json’ 返回结构化JSON

  • temperature (float, optional) – 控制输出随机性的温度参数，范围 0-2。值越高输出越随机

  • top_p (float, optional) – 核采样参数，范围 0-1。与 temperature 一起控制输出多样性

  • frequency_penalty (float, optional) – 频率惩罚参数，范围 -2 到 2。正值减少重复内容

  • presence_penalty (float, optional) – 存在惩罚参数，范围 -2 到 2。正值鼓励谈论新主题

  • seed (int, optional) – 随机种子，用于获得可重现的输出

  • max_tokens (int, optional) – 生成的最大令牌数

  • stop (List[str], optional) – 停止序列列表，遇到这些序列时停止生成

Returns:

API 响应内容。如果 response_format=’text’ 返回字符串， 如果 response_format=’json’ 返回解析后的字典

Return type:

str or Dict[str, Any]

Raises:

  • ValueError – 当 response_format 不是 ‘text’ 或 ‘json’ 时， 或当请求 JSON 格式但消息中不包含 JSON 指令时

  • json.JSONDecodeError – 当 JSON 响应无法解析时

call_embed(input: str, model: str) → list[float][source]

获取文本的嵌入表示

Parameters:

  • input (str) – 要嵌入的文本输入

  • model (str) – 使用的嵌入模型名称，例如 ‘text-embedding-3-large’

Returns:

嵌入向量列表

Return type:

List[float]

clear_history() → None[source]

清空调用历史

get_last_response() → str | dict[str, Any] | None[source]

获取最后一次调用的响应

print_history() → None[source]

打印调用历史记录

Key Features

  • Automatic Configuration: Uses environment variables for API key and base URL

  • Flexible Input: Accepts both string messages and structured conversation arrays

  • JSON Mode: Built-in support for structured JSON responses

  • History Tracking: Maintains a history of all API calls

  • Streaming Support: Real-time response streaming

  • Error Handling: Comprehensive error handling and logging

Usage Examples

Basic Text Generation

from lmitf import BaseLLM

llm = BaseLLM()
response = llm.call("What is machine learning?")
print(response)

JSON Mode

# Get structured output
profile = llm.call_json(
    "Generate a user profile with name, age, and occupation",
    model="gpt-4"
)
print(profile)  # Returns a dictionary

Conversation with Context

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What's the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "What's its population?"}
]

response = llm.call(messages, model="gpt-4")
print(response)

Streaming Responses

# Stream responses for real-time output
response_stream = llm.call(
    "Write a short story about AI",
    model="gpt-4",
    stream=True
)

for chunk in response_stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Configuration

Environment Variables

The BaseLLM class automatically reads configuration from environment variables:

export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://api.openai.com/v1"

Manual Configuration

You can also provide credentials directly:

llm = BaseLLM(
    api_key="your-api-key",
    base_url="https://your-custom-endpoint.com/v1"
)

Method Reference

call()

Main method for generating text responses.

Parameters:

  • messages (str | list): Input message(s)

  • model (str): Model to use (default: “gpt-4o”)

  • stream (bool): Enable streaming responses

  • **kwargs: Additional OpenAI API parameters

Returns:

  • str: Generated response text (non-streaming)

  • Iterator: Streaming response chunks (streaming)

call_json()

Generate structured JSON responses.

Parameters:

  • messages (str | list): Input message(s)

  • model (str): Model to use (default: “gpt-4o”)

  • **kwargs: Additional OpenAI API parameters

Returns:

  • dict: Parsed JSON response

Error Handling

The class includes comprehensive error handling:

try:
    response = llm.call("Hello", model="invalid-model")
except Exception as e:
    print(f"API Error: {e}")

Best Practices

  1. Use Environment Variables: Store API credentials in .env files

  2. Handle Errors: Always wrap API calls in try-catch blocks

  3. Monitor Usage: Check call_history to track API usage

  4. Choose Appropriate Models: Use different models based on task complexity

  5. Use JSON Mode: For structured data extraction tasks