备注
Go to the end to download the full example code.
模型 API
AgentScope 已集成了许多不同模态的模型 API 。
备注
API |
对话 |
文本生成 |
视觉 |
Embedding |
---|---|---|---|---|
OpenAI |
✓ |
✗ |
✓ |
✓ |
DashScope |
✓ |
✗ |
✓ |
✓ |
Gemini |
✓ |
✗ |
✗ |
✓ |
Ollama |
✓ |
✓ |
✓ |
✓ |
Yi |
✓ |
✗ |
✗ |
✗ |
LiteLLM |
✓ |
✗ |
✗ |
✗ |
ZhipuAI |
✓ |
✗ |
✗ |
✓ |
Anthropic |
✓ |
✗ |
✗ |
✗ |
在 AgentScope 中使用模型 API 有两种方式。可以根据自己的需求进行选择:
使用模型配置:这是构建与模型 API 无关的应用程序的推荐方式。可以通过修改配置来更改模型 API,而无需更改智能体代码。
显式初始化模型:如果只想使用特定的模型 API,显式初始化模型会更加方便和透明。API 文档字符串提供了参数和用法的详细信息。
小技巧
实际上,使用配置和显式初始化模型是等效的。使用模型配置时,AgentScope 只是将配置中的键值对传递给模型的构造函数。
import os
from agentscope.models import (
DashScopeChatWrapper,
ModelWrapperBase,
ModelResponse,
)
import agentscope
使用配置
在模型配置中,需要提供以下三个字段:
config_name:配置的名称。
model_type:模型 API 的类型,例如 “dashscope_chat”、”openai_chat” 等。
model_name:模型的名称,例如 “qwen-max”、”gpt-4o” 等。
在使用模型 API 之前通过调用 agentscope.init() 来加载配置,如下所示:
agentscope.init(
model_configs=[
{
"config_name": "gpt-4o_temperature-0.5",
"model_type": "openai_chat",
"model_name": "gpt-4o",
"api_key": "xxx",
"temperature": 0.5,
},
{
"config_name": "my-qwen-max",
"model_type": "dashscope_chat",
"model_name": "qwen-max",
},
],
)
[]
对于其它可选参数,可以查看对应模型 API 的构造函数的说明。
显式初始化模型
agentscope.models 模块提供了所有的内置模型 API。 您可以通过调用相应的模型类来显式初始化模型。
# 打印 agentscope.models 下的模块
for module_name in agentscope.models.__all__:
if module_name.endswith("Wrapper"):
print(module_name)
PostAPIChatWrapper
OpenAIChatWrapper
OpenAIDALLEWrapper
OpenAIEmbeddingWrapper
DashScopeChatWrapper
DashScopeImageSynthesisWrapper
DashScopeTextEmbeddingWrapper
DashScopeMultiModalWrapper
OllamaChatWrapper
OllamaEmbeddingWrapper
OllamaGenerationWrapper
GeminiChatWrapper
GeminiEmbeddingWrapper
ZhipuAIChatWrapper
ZhipuAIEmbeddingWrapper
LiteLLMChatWrapper
YiChatWrapper
AnthropicChatWrapper
以 DashScope Chat API 为例:
model = DashScopeChatWrapper(
config_name="_",
model_name="qwen-max",
api_key=os.environ["DASHSCOPE_API_KEY"],
stream=False,
)
response = model(
messages=[
{"role": "user", "content": "嗨!"},
],
)
response 是 agentscope.models.ModelResponse 的一个对象,它包含以下字段:
text:生成的文本
embedding:生成的嵌入
image_urls:引用生成的图像
raw:来自 API 的原始响应
parsed:解析后的响应,例如将字符串解析成 JSON 对象
stream:用来挂载流式响应的生成器,更多详情请参考 流式输出 一节。
print(f"文本:{response.text}")
print(f"嵌入:{response.embedding}")
print(f"图像URL:{response.image_urls}")
print(f"原始响应:{response.raw}")
print(f"解析后响应:{response.parsed}")
print(f"流响应:{response.stream}")
文本:你好!有什么可以帮助你的吗?
嵌入:None
图像URL:None
原始响应:{"status_code": 200, "request_id": "4d97580a-991f-96e8-a65e-7a90082a6dbd", "code": "", "message": "", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "stop", "message": {"role": "assistant", "content": "你好!有什么可以帮助你的吗?"}}]}, "usage": {"input_tokens": 10, "output_tokens": 7, "prompt_tokens_details": {"cached_tokens": 0}, "total_tokens": 17}}
解析后响应:None
流响应:None
集成新的 LLM API
将新的 LLM API 集成到 AgentScope 有两种方式。
OpenAI 兼容 API
如果您的模型与 OpenAI Python API 兼容,建议重用 OpenAIChatWrapper 类并提供特定参数。
备注
需要确保 API 的回复同样兼容 OpenAI Python API。
以 vLLM 为例, 其 官方文档 提供了以下使用 OpenAI Python 库的示例:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="token-abc123",
)
completion = client.chat.completions.create(
model="NousResearch/Meta-Llama-3-8B-Instruct",
messages=[
{"role": "user", "content": "Hello!"}
],
temperature=0.5,
)
print(completion.choices[0].message)
将 vLLM 集成到 AgentScope 非常简单,如下:
将初始化 OpenAI 客户端的参数(除了 api_key)放入 client_args,
将生成完成的参数(除了 model)放入 generate_args。
vllm_model_config = {
"model_type": "openai_chat",
"config_name": "vllm_llama2-7b-chat-hf",
"model_name": "meta-llama/Llama-2-7b-chat-hf",
"api_key": "token-abc123", # API 密钥
"client_args": {
"base_url": "http://localhost:8000/v1/", # 用于指定 API 的基础 URL
},
"generate_args": {
"temperature": 0.5, # 生成参数,如 temperature、seed
},
}
或者,直接用参数初始化 OpenAI Chat API 的模型类:
from agentscope.models import OpenAIChatWrapper
model = OpenAIChatWrapper(
config_name="",
model_name="meta-llama/Llama-2-7b-chat-hf",
api_key="token-abc123",
client_args={"base_url": "http://localhost:8000/v1/"},
generate_args={"temperature": 0.5},
)
RESTful API
如果您的模型通过 RESTful post API 访问,并且响应格式与 OpenAI API 兼容,可以考虑使用 PostAPIChatWrapper。
以下面的 curl 命令为例,只需将 header、API URL 和 data(除了 messages,它将自动传递)提取成模型类的初始化参数即可。
一个示例 post 请求:
curl https://api.openai.com/v1/chat/completions
-H "Content-Type: application/json"
-H "Authorization: Bearer $OPENAI_API_KEY"
-d '{
"model": "gpt-4o",
"messages": [
{"role": "user", "content": "write a haiku about ai"}
]
}'
相应的模型类初始化如下:
from agentscope.models import PostAPIChatWrapper
post_api_model = PostAPIChatWrapper(
config_name="",
api_url="https://api.openai.com/v1/chat/completions", # 目标 URL
headers={
"Content-Type": "application/json", # 来自头部
"Authorization": "Bearer $OPENAI_API_KEY",
},
json_args={
"model": "gpt-4o", # 来自数据
},
)
它的模型配置如下:
post_api_config = {
"config_name": "{my_post_model_config_name}",
"model_type": "post_api_chat",
"api_url": "https://api.openai.com/v1/chat/completions",
"headers": {
"Authorization": "Bearer {YOUR_API_TOKEN}",
},
"json_args": {
"model": "gpt-4o",
},
}
如果你的模型 API 返回格式与 OpenAI 不同,可以继承 PostAPIChatWrapper 并重写 _parse_response 方法。
备注
需要在子类中定义一个新的 model_type 字段,以区分它与现有的模型类。
class MyNewModelWrapper(PostAPIChatWrapper):
model_type: str = "{my_new_model_type}"
def _parse_response(self, response: dict) -> ModelResponse:
"""解析来自 API 服务器的响应。
Args:
response (`dict`):
从 API 服务器获取的响应,并通过
`response.json()` 解析为统一的格式。
Returns (`ModelResponse`):
解析后的响应。
"""
# TODO: 将以下代码替换为您自己的解析逻辑
return ModelResponse(
text=response["data"]["response"]["choices"][0]["message"][
"content"
],
)
自定义模型类
如果需要从头开始实现新的模型类,首先需要了解 AgentScope 中的以下概念:
model_type:在使用模型配置时,AgentScope 使用 model_type 字段来区分不同的模型 API。因此,请确保您的新模型类具有唯一的 model_type。
__init__:从模型配置初始化时,AgentScope 会将配置中的所有键值对传递给模型类的 __init__ 方法。因此,请确保您的 __init__ 方法可以处理配置中的所有参数。
__call__:模型类的核心方法是 __call__,它接收输入消息并返回响应。其返回值应该是 ModelResponse 对象。
class MyNewModelWrapper(ModelWrapperBase):
model_type: str = "{my_new_model_type}"
def __init__(self, config_name, model_name, **kwargs) -> None:
super().__init__(config_name, model_name=model_name)
# TODO: 在这里初始化您的模型
def __call__(self, *args, **kwargs) -> ModelResponse:
# TODO: 在这里实现您的模型的核心逻辑
return ModelResponse(
text="Hello, World!",
)
小技巧
可选地,可以在模型中实现一个 format 方法,从而将 AgentScope 中的 Msg 类 转化为目标模型 API 要求的格式。更多详情请参考 提示工程。
进一步阅读
Total running time of the script: (0 minutes 1.920 seconds)