跳到主要内容

模型使用基础

模型是 Agent 的核心能力来源。AgentRun 提供了统一的模型管理接口，屏蔽不同模型供应商的 API 差异，让您可以用一致的方式调用各种大语言模型。本章将介绍如何创建和使用模型，以及如何在实际应用中发挥模型的最大价值。

理解模型服务与模型代理​

AgentRun 支持两种模型接入方式：ModelService（模型服务） 和 ModelProxy（模型代理）。理解它们的区别有助于您根据实际需求选择合适的方案。

  • ModelService 用于接入您自己部署的模型服务。
    如果您在自己的服务器或容器中运行了开源模型（如 Llama、ChatGLM 等），或者在 FunModel 平台搭建了私有化的模型推理服务，可以通过 ModelService 将这些服务注册到 AgentRun 平台。ModelService 会记录您的服务端点信息和认证配置，当 Agent 调用模型时，请求会被转发到您的服务地址。
  • ModelProxy 则是一个更高级的抽象，提供了模型治理能力。
    它可以代理一个或多个模型服务，并在其上实现负载均衡、故障转移、请求限流等企业级特性。例如，您可以创建一个 ModelProxy，配置多个后端模型（可能来自不同供应商），当某个模型响应缓慢或出现故障时，请求会自动路由到其他可用的模型。这种机制大大提升了 Agent 应用的可靠性和性能。
使用建议

对于大多数场景，建议使用 ModelProxy。即使您只有一个模型，通过 ModelProxy 也能获得更好的监控、限流、错误处理等能力。

往下阅读前的一些提示

在接下来的部分，我们给出了一些代码示例，这需要您提前配置好开发环境，包括

  • 安装 AgentRun 及相关的依赖库
  • 配置阿里云的密钥信息到环境变量

相关操作可见 安装与配置

创建资源​

创建模型服务​

创建模型服务需要提供服务的基本信息和访问配置。以下示例展示了如何通过 SDK 创建一个 ModelService：

from agentrun.model import (
    ModelClient, ModelService, ModelServiceCreateInput,
    ProviderSettings, ModelType
)

input = ModelServiceCreateInput(
    model_service_name="my-agentrun-model-service",
    description="测试模型服务",
    model_type=ModelType.LLM,
    provider="tongyi",
    provider_settings=ProviderSettings(
        # 这里要替换成您的模型 api key
        api_key="sk-*******",
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
        model_names=["qwen3-max"],
    ),
)

# 可以使用使用静态方法创建资源
ms = ModelService.create(input)

# 也可以使用 client 创建资源
# client = ModelClient()
# ms = client.create(input)

print(f"模型服务创建成功: {ms.model_service_name}")
# 模型服务创建成功 my-agentrun-model-service

在这个例子中，我们创建了一个指向阿里云百炼的模型服务。provider 参数指定模型供应商，SDK 会根据供应商类型处理请求格式转换。

创建模型治理​

ModelProxy 的创建过程与 ModelService 类似，但需要配置后端模型列表和路由策略：

此外，模型治理需要访问 AgentRun 的资源以获取您配置的 API KEY 等信息。由于模型治理运行程序在您的账号下，需要拥有权限才能访问您的 AgentRun 资源。 因此您还需要创建一个拥有 AgentRun 权限的角色提供给模型治理进程。

为了提升安全性，您不需要将阿里云密钥配置到环境变量中，取而代之的是通过角色进行授权。当您为 AgentRun/函数计算 配置了角色后，您的程序在启动时将会自动根据角色权限注入临时密钥到环境变量。及时由于意外问题导致密钥泄漏，该临时密钥也会在固定时间后自动过期，减少损失。

通常，在 AgentRun 场景下，您需要为角色配置如下权限

  • AliyunAgentRunFullAccess: 允许您的代码访问 AgentRuntime、Sandbox、Model、Credential 等能力
  • AliyunDevsFullAccess: 允许您的代码访问 ToolSet

如果您还需要访问其他云产品，则可以按需增加权限。对于特定业务场景，您也可以进行精确授权，如仅授予某个资源的读权限。更多信息可以参考 RAM角色概览

如果您需要快速创建一个拥有 AliyunAgentRunFullAccess 和 AliyunDevsFullAccess 权限的角色，则可以点击 快速授权链接

from agentrun.model import (
    ModelClient, ModelProxy, ModelProxyCreateInput, ProviderSettings,
    ModelType, ProxyConfig, ProxyConfigEndpoint
)

input =  ModelProxyCreateInput(
    model_proxy_name="my-agentrun-model-proxy",
    description="测试模型治理",
    model_type=ModelType.LLM,
    # 模型治理需要您配置一个拥有 AgentRun 权限的角色
    execution_role_arn=f"acs:ram::{cfg.get_account_id()}:role/AliyunAgentRunDefaultRole",
    proxy_config=ProxyConfig(
        endpoints=[
            ProxyConfigEndpoint(
                model_names=[ "qwen3-max" ],
                model_service_name="my-agentrun-model-service",
                weight=70,
            ),
            ProxyConfigEndpoint(
                model_names=[ "deepseek-v3" ],
                model_service_name="my-agentrun-model-service-2",
                weight=30,
            )
        ],
    ),
)

# 可以使用使用静态方法创建资源
ms = ModelProxy.create(input)

# 也可以可以使用 client 创建资源
# client = ModelClient()
# ms = client.create(input)

print(f"模型治理创建成功: {ms.name}")
# 模型治理创建成功: my-agentrun-model-proxy

这个配置创建了一个支持负载均衡的模型治理，70% 的请求会路由到 qwen3-max，30% 路由到 deepseek-v3。这种配置既保证了成本效益，又能让部分请求享受到更强大模型的能力。

基础对话​

模型创建完成后，就可以进行对话调用了。无论是模型服务还是模型治理，均可以通过相同的方式进行后续操作。

创建完成后，您可以通过服务名称获取模型对象并进行调用：

from agentrun.model import ModelService

# 可以使用使用静态方法创建资源
ms = ModelService.get_by_name("my-agentrun-model-service")

# 也可以使用 Client 获取已经创建的模型服务
# client = ModelClient()
# ms = client.get("my-agentrun-model-service")

print(f"模型服务获取成功: {ms.model_service_name}")
# 模型服务获取成功 my-agentrun-model-service
模型服务与模型代理

无论是模型服务还是模型代理，都来源于 AgentRun 模型模块。因此在使用 ModelClient 时，SDK 会根据参数自动识别您希望请求的是模型服务还是模型治理。

对于 Get 场景，则会依次请求两者的接口，如果您不希望非预期的 404 请求，则可以使用对应的类静态方法进行请求，或传入 backend_type 参数

AgentRun SDK 提供了 completions 方法来发起对话请求：

from agentrun.model import ModelService

# 无论是模型服务还是模型治理，操作均是相同的，以模型服务为例
ms = ModelService.get_by_name("my-agentrun-model-service")
print(f"模型服务获取成功: {ms.model_service_name}")
# 模型服务获取成功: my-agentrun-model-service

result = ms.completions([{"role": "user", "content": "AgentRun 有几个字母？"}])

print(result.choices[0].message.content)
# “AgentRun” 一共有 9 个字母。
备注

在 Python SDK 中，底层使用的是 LiteLLM，您的其他命名参数将会被传入 LiteLLM

流式输出​

from agentrun.model import ModelService

# 无论是模型服务还是模型治理，操作均是相同的，以模型服务为例
ms = ModelService.get_by_name("my-agentrun-model-service")
print(f"模型服务获取成功: {ms.model_service_name}")
# 模型服务获取成功: my-agentrun-model-service

result = ms.completions(
    [{"role": "user", "content": "AgentRun 有几个字母？"}], stream=True
)


for chunk in result:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)
# “AgentRun” 一共有 9 个字母。
备注

在 Python SDK 中，底层使用的是 LiteLLM，您的其他命名参数将会被传入 LiteLLM

自行构建 LLM Client​

在一些场景，您可能需要使用一些模型支持，但 AgentRun SDK 暂不支持的能力。此时，您可以手动构建原生模型客户端，如同传统方式一样使用大模型

要完成这一点，您只需要通过 model_info() 方法获取模型调用相关的参数信息。需要注意，headers 请一并传入您的 LLM Client，如果您在 AgentRun 配置了凭证，相关的 token 会写入到 headers 中

from agentrun.model import ModelService

# 无论是模型服务还是模型治理，操作均是相同的，以模型服务为例
ms = ModelService.get_by_name("my-agentrun-model-service")
print(f"模型服务获取成功: {ms.model_service_name}")
# 模型服务获取成功: my-agentrun-model-service

info = ms.model_info()
print(info)
# model='qwen3-max' api_key='sk-***********' base_url='https://dashscope.aliyuncs.com/compatible-mode/v1' headers={} provider=None