百炼大模型系列调用教程#

Available at MaxFrame 2.6.0

本文介绍如何在 MaxFrame 中访问百炼公共模型集提供的模型及操作示例。

本文包括：

  • 浏览 BIGDATA_PUBLIC_MODELSET 中可用的模型。

  • 查看模型元信息与推理参数。

  • 文本 Embedding 推理。

  • 文本生成推理。

  • 将推理结果写入 MaxCompute 表。

前提条件#

#

条件

说明

1

开通 MaxCompute

需要一个已开通的 MaxCompute 项目，并具备有效的 Access ID / Access Key。

2

开通 DPE 引擎

本流程中的百炼 AI Function 调用通过 DPE 执行。

3

购买模型计算服务

在 MaxCompute 控制台购买模型计算服务；系统将创建推理配额并按使用量计费。

4

支持地域

请确保 MaxCompute 项目所在地域支持百炼模型服务。

5

Python 版本

推荐使用 Python 3.11。

6

MaxFrame SDK 版本

请使用 MaxFrame SDK 2.6.0 及以上版本（pip install maxframe>=2.6.0）。

模型计算服务与推理配额#

在 MaxCompute 控制台购买或开通模型计算服务，并在运行百炼模型推理前确认已关联推理配额。

MaxCompute 模型计算服务购买页面

1. 环境准备与会话创建#

检查 MaxFrame 版本：

import maxframe

assert maxframe.__version__ >= "2.6.0", (
    f"maxframe >= 2.6.0 is required, current version: {maxframe.__version__}. "
    f"Please run: pip install --upgrade maxframe"
)
print(f"maxframe version: {maxframe.__version__} ✓")

导入依赖：

import logging

import pandas as pd
import maxframe.dataframe as md
from maxframe import new_session
from maxframe.config import options
from maxframe.learn.utils import read_odps_model
from odps import ODPS

logging.basicConfig(level=logging.INFO)
pd.set_option("display.max_colwidth", None)
pd.set_option("display.max_columns", None)

配置引擎并创建会话：

o = ODPS(
    access_id="<your_access_id>",
    secret_access_key="<your_access_key>",
    endpoint="https://service.<region>.maxcompute.aliyun.com/api",
    project="<your_project_name>",
)

options.dag.settings = {"engine_order": ["DPE", "MCSQL"]}
options.session.inference_quota_name = "<your_inference_quota_name>"

session = new_session(o)
print(f"Session ID : {session.session_id}")
print(f"LogView    : {session.get_logview_address()}")

备注

请保存 LogView 地址以便排障。它是查看 Worker 日志和运行时诊断信息的核心入口。

2. 浏览百炼公共模型集#

available_models = list(o.list_models(project="bigdata_public_modelset"))
print(f"Available model count: {len(available_models)}")
for m in available_models:
    print(f"  - {m.name}")

3. 查看模型详情#

model = o.get_model("text-embedding-v4", project="bigdata_public_modelset")

print(f"name: {model.name}")
print(f"type: {model.type}")
print(f"source_type: {model.source_type}")
print(f"options: {model.options}")
print(f"_feature_columns: {model._feature_columns}")
print(f"inference_parameters: {model.inference_parameters}")
print(f"_labels: {model._labels}")

4. 文本 Embedding 推理#

加载 Embedding 模型：

embedding_model = read_odps_model("text-embedding-v4", project="bigdata_public_modelset")
print(embedding_model)

准备输入数据：

query_list = [
    "What is the average distance from Earth to the Sun?",
    "When did the American Revolutionary War begin?",
    "What is the boiling point of water?",
    "How can I quickly relieve a headache?",
    "Who is the main character in Harry Potter?",
]

df = md.DataFrame({"query": query_list})

调用 embed()：

# simple_output=True returns the raw embedding data directly,
# skipping provider response metadata.
embedding_result = embedding_model.embed(
    df["query"],
    simple_output=True,
)

print("Output dtypes:")
print(embedding_result.dtypes)

触发执行：

embedding_executed = embedding_result.execute()
print("Embedding result:")
print(embedding_executed)

5. 文本生成推理#

加载生成模型：

gen_model = read_odps_model("qwen3-max", project="bigdata_public_modelset")
print(gen_model)

构造 Prompt 并执行：

messages = [
    {"role": "system", "content": "You are a concise and accurate QA assistant."},
    {"role": "user", "content": "{query}"},
]

# simple_output=True returns the generated text directly,
# skipping the raw provider response structure.
gen_result = gen_model.generate(
    df,
    prompt_template=messages,
    simple_output=True,
)

gen_executed = gen_result.execute()
print("Generation result:")
print(gen_executed)

可选：结果持久化

# md.to_odps_table(embedding_result, "bailian_embedding_results", overwrite=True).execute()
# md.to_odps_table(gen_result, "bailian_generate_results", overwrite=True).execute()

6. 资源清理#

session.destroy()
print("Session destroyed and resources released.")

附录：百炼模型 vs 内置托管模型#

对比项

百炼预注册模型

内置托管模型

加载 API

read_odps_model("name", project="bigdata_public_modelset")

ManagedTextGenLLM(name="...")

来源

百炼平台已注册模型

MaxFrame 托管模型目录

典型模型名

text-embedding-v4, qwen3-max

qwen2.5-1.5b-instruct, DeepSeek-R1

推理方法

generate() / embed()

generate() / embed() / translate() / extract()

内置托管模型示例：

from maxframe.learn.contrib.llm.models.managed import ManagedTextGenLLM

llm = ManagedTextGenLLM(name="qwen2.5-1.5b-instruct")
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "{query}"},
]
# simple_output=True returns the generated text directly,
# skipping the raw provider response structure.
result = llm.generate(df, prompt_template=messages, simple_output=True)
result.execute()

常见问题排查#

问题

原因

解决方案

Engine DPE not available

项目未开通 DPE

联系管理员开通 DPE 引擎。

Model not found

模型名称错误或地域不支持

使用 list_models() 确认可用模型，并检查地域支持情况。

inference_quota_name 报错

推理配额未配置

请设置有效的 options.session.inference_quota_name。

Session timeout

推理任务超时

减少批次大小并通过 LogView 排查日志。

execute() 无返回

懒执行计算图尚未触发

确认已调用 .execute()。