BaseLLM API Reference

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

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)

初始化 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 = 'json', 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]

调用 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]

获取文本的嵌入表示

Parameters:

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

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

Returns:

嵌入向量列表

Return type:

List[float]

clear_history() → None

清空调用历史

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

获取最后一次调用的响应

print_history() → None

打印调用历史记录

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

从字符串中提取第一个 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)

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)

初始化 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 = 'json', 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]

调用 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]

获取文本的嵌入表示

Parameters:

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

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

Returns:

嵌入向量列表

Return type:

List[float]

clear_history() → None

清空调用历史

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

获取最后一次调用的响应

print_history() → None

打印调用历史记录

Key Features

• Simple API Interface: Easy-to-use wrapper for OpenAI-compatible APIs

• Message Support: Accepts both string messages and structured conversation arrays

• Conversation History: Tracks and displays conversation history

• Embedding Support: Generate text embeddings with call_embed method

• Template Integration: Works with template-based prompts

Usage Examples

Single Question Answering

from lmitf import BaseLLM

llm = BaseLLM()
response = llm.call(
    messages=[{'role': 'user', 'content': 'Who is the president of the United States?'}],
    response_format='text',
)
llm.print_history()

Multi-turn Conversation

# Continue conversation using call_history
q1 = "Where is the president from?"
res = llm.call(
    messages=llm.call_history + [{'role': 'user', 'content': q1}],
    response_format='text',
)
llm.print_history()

Text Embeddings

# Generate embeddings for text
text = "hello world"
embedding = llm.call_embed(
    input=text,
    model="text-embedding-3-large"
)
print(f"embedding shape: {embedding.shape}")

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 (list): List of message dictionaries with ‘role’ and ‘content’

• response_format (str): Response format (default: ‘text’)

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

• **kwargs: Additional OpenAI API parameters like temperature

Returns:

• str: Generated response text

call_embed()

Generate text embeddings.

Parameters:

• input (str): Text to embed

• model (str): Embedding model to use (e.g., “text-embedding-3-large”)

Returns:

• numpy.ndarray: Text embedding vector

print_history()

Display conversation history with formatted output.

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

Related Classes

• BaseLVM - For vision-language tasks

• TemplateLLM - For template-based workflows