Large Language Model大语言模型

VioletAgentsLLM 类的作用

VioletAgentsLLM 是一个统一的 LLM（大语言模型）调用接口，封装了 OpenAI 兼容 API 的客户端，让你可以用统一的方式调用不同的 LLM 服务提供商。

在本框架中，作为Agent基类的参数以便LLM（大语言）模型调用。

支持非流式输出、暂未支持流式输出（待开发）

核心职责

1. 多提供商支持：内置支持 deepseek 和 modelscope 两个服务商
2. 智能配置解析：通过三级优先级来解析配置参数：
   • 构造函数参数 > 提供商专用环境变量 > 通用环境变量
   • 例如 deepseek 的 API Key 在provider="deepseek"情况下会依次查找：api_key 参数 → DEEPSEEK_API_KEY 环境变量 → LLM_API_KEY 环境变量
3. 自动检测提供商：_auto_detect_provider() 方法会根据 base_url 中的域名自动判断是 DeepSeek（api.deepseek.com）还是 ModelScope（dashscope.aliyuncs.com），否则使用通用配置（读取LLM_API_KEY、LLM_BASE_URL、LLM_MODEL_NAME）。
4. 对话调用：chat() 方法封装了 OpenAI 的 chat.completions.create，支持传入消息列表、工具（tools）和工具选择策略（tool_choice），并自动处理 Message 对象到 OpenAI 字典格式的转换。

VioletAgentsLLM构造函数参数说明

参数	类型	默认值	说明
provider	"deepseek" / "modelscope" / "auto"	自动检测	核心参数。指定 LLM 服务提供商，决定从哪些环境变量读取配置以及使用哪个默认模型。不填时根据 传入的base_url或LLM_BASE_URL 自动识别
model	str	自动获取	模型名称。不填时依次读取 ${PROVIDER}_MODEL_NAME → LLM_MODEL_NAME，都未设置则使用 provider 默认模型
base_url	str	自动获取	API 地址。不填时依次读取 ${PROVIDER}_BASE_URL → LLM_BASE_URL
api_key	str	自动获取	API 密钥。不填时依次读取 ${PROVIDER}_API_KEY → LLM_API_KEY
temperature	float	0.7	输出随机性（0~2）。越低越确定，越高越多样
max_tokens	int	None	单次输出最大 token 数。None 表示不限制
timeout	int	None	请求超时时间（秒）。None 使用 SDK 默认值
**kwargs	-	-	传递给 OpenAI 客户端的额外参数

TIP

provider 值直接决定了 ${PROVIDER} 读取哪些环境变量。例如 provider="deepseek" 时，会读取 DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL、DEEPSEEK_MODEL_NAME。

自动检测提供商机制

以下 LLM 服务提供商支持自动检测

• DeepSeek
• modelscope

provider参数在未传入参数时会根据base_url参数或LLM_BASE_URL进行自动识别。识别优先级：base_url>LLM_BASE_URL

若识别为支持的大模型服务商，接下来读取的优先级如下：

• 构造函数参数 > 提供商专用环境变量 > 通用环境变量

并且在参数model和${PROVIDER_MODEL_NAME}为空的情况下会自动填入对应的轻量模型

若识别为不支持的大模型服务商，接下来的读取优先级如下：

• 构造函数参数 > 通用环境变量

在参数model或LLM_MODEL_NAME为空的情况下会抛出异常

环境变量名解释

• 通用环境变量：

  • LLM_API_KEY: LLM服务密钥，优先级低于各自服务的专用环境变量

  • LLM_BASE_URL: LLM服务地址，优先级低于各自服务的专用环境变量

  • LLM_MODEL_NAME: 模型名称，优先级低于各自服务的专用环境变量

• Deepseek专用环境变量：

  • DEEPSEEK_API_KEY
  • DEEPSEEK_BASE_URL
  • DEEPSEEK_MODEL_NAME

• Modelscope专用环境变量：

  • MODELSCOPE_API_KEY
  • MODELSCOPE_BASE_URL
  • MODELSCOPE_MODEL_NAME

在provider有效情况下，若参数、环境变量读取不到model名称，则使用模型列表：

• deepseek: deepseek-v4-flash
• modelscope: qwen3.5-flash

使用方法

不使用环境变量调用

当你不想使用环境变量时

from violet_agents import VioletAgentsLLM
llm = VioletAgentsLLM(api_key="your_api_key_here",
                    base_url="your_base_url_here", 
                    model="your_model_here")

推荐用法

支持自动检测的大语言模型

若你使用的LLM 服务提供商为本框架支持的，推荐用法：

• 配置环境变量${PROVIDER}_API_KEY、${PROVIDER}_MODEL_NAME
• VioletAgentsLLM(provider="${PROVIDER}")

比如

from violet_agents import VioletAgentsLLM
llmA = VioletAgentsLLM(provider="deepseek")
llmB = VioletAgentsLLM(provider="modelscope")

上述用法在你没有设置${PROVIDER}_MODEL_NAME且并没有赋值model的情况下框架会默认采用对应LLM 服务提供商的轻量模型。若你想在单次调用中自定义对应服务商的指定模型，推荐以下用法

from violet_agents import VioletAgentsLLM
llmA = VioletAgentsLLM(provider="deepseek", model="deepseek-v4-pro")

或者你可以通过修改环境变量（PROVIDER_MODEL_NAME）来改变本框架在未指定模型情况下使用的默认模型

不支持自动检测的大语言模型

若你使用的LLM 服务提供商非本框架支持，推荐用法：

配置环境变量LLM_API_KEY，LLM_MODEL_NAME，LLM_MODEL_NAME

from violet_agents import VioletAgentsLLM
llmA = VioletAgentsLLM()

当你想使用VioletAgentsLLM()时，注意：

使用该无参构造函数必须确保LLM_BASE_URL存在

支持自动检测的LLM，在使用VioletAgentsLLM的无参构造函数时，需要确保环境变量${PROVIDER}_API_KEY或LLM_API_KEY存在即可（未指定模型会使用服务商对应的轻量模型）

不支持自动检测的LLM，在使用VioletAgentsLLM的无参构造函数时，需要确保LLM_API_KEY和LLM_MODEL_NAME存在

最佳实践

以下是VioletAgentsLLM在实际中最常见的应用

agent = SimpleAgent(
    name="helloAgent",
    llm=VioletAgentsLLM(provider="deepseek", model="deepseek-v4-pro"),
    system_prompt="你是一个简单的助手，直接回答用户的问题，不进行复杂的思考和计划。"
)

response = agent.run("你好")