2.1 依赖引入

在 App 模块的 build.gradle 中添加：

dependencies {
    implementation 'com.umeng.umsdk:common:+'   // 最低版本要求 9.9.9
    implementation 'com.umeng.umsdk:asms:+'
}

若 + 动态版本解析到低于 9.9.9 的版本，请显式固定版本：

implementation 'com.umeng.umsdk:common:9.9.9'（或更高的确定版本）。

2.2 权限声明

在 AndroidManifest.xml 中声明以下权限（友盟 Common SDK 通常已自动合入，如有缺失请手动补充）：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

2.3 Application 中初始化

在自定义 Application.onCreate() 中完成友盟初始化：

import com.umeng.commonsdk.UMConfigure;

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        // 预初始化（必须在 UMConfigure.init 之前调用）
        UMConfigure.preInit(this, "YOUR_APPKEY", "default_channel");

        // 正式初始化（UMADK 与 UMConfigure 使用同一 appKey 注册，见 3.2）
        UMConfigure.init(this, "YOUR_APPKEY", "default_channel",
                UMConfigure.DEVICE_TYPE_PHONE, "");
    }
}

2.4 混淆规则

友盟 Common SDK 自带 consumer-rules，正常情况下无需额外配置。若遇到混淆异常，可手动补充：

-keep class com.umeng.** { *; }


-keep class org.repackage.** { *; }


- keepclassmembers class * {

    public <init>(org.json.JSONObject);
}

3.1 依赖引入

方式一：Maven 在线依赖（推荐）

在 App 模块的 build.gradle 中添加：

dependencies {
    implementation 'com.umeng.umsdk:adk:1.1.0'

    // OkHttp 3.12.13 LTS — ADK 运行时必需依赖
    implementation 'com.squareup.okhttp3:okhttp:3.12.13'
}

方式二：本地 AAR 引入

将 ADK AAR 文件（如 adk-release.aar）放置于 App 模块的 libs/ 目录，并在 build.gradle 中添加：

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])

    // OkHttp 3.12.13 LTS — ADK 运行时必需依赖
    implementation 'com.squareup.okhttp3:okhttp:3.12.13'
}

注意：两种方式等效。ADK SDK 以 compileOnly 方式依赖 OkHttp 和友盟 Common SDK，不会打入产物。宿主 App 必须自行引入上述依赖（友盟 Common SDK 见第二章）。

3.2 初始化

ADK SDK 初始化通过 UADK.prepare(InitCallback) 完成，在 UMConfigure

初始化之后调用（appKey 与 UMConfigure 使用同一注册值，

UMCommon ≥ 9.9.9 初始化完成时 SDK 配置自动就绪，无需其他调用）：

完整示例：

import com.umeng.adk.UADK;
import com.umeng.adk.InitCallback;
import com.umeng.adk.UADKError;

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        // 友盟初始化（略；必须先于 UADK 初始化）

        // ADK 初始化
        UADK.prepare(new InitCallback() {
            @Override
            public void onSuccess() {
                // SDK 就绪，可调用业务接口
            }

            @Override
            public void onError(UADKError error) {
                // 初始化失败，根据 error.getCode() 与 error.getSource() 判断原因
            }
        });
    }
}

3.3 调试模式

开发阶段可开启调试日志（release 包中建议关闭）：

UADK.setDebugMode(BuildConfig.DEBUG);

调试模式开启后，SDK 将输出详细日志（凭证字段自动脱敏）。可通过 UADK.isDebugMode() 查询当前状态。

4.1 非流式聊天

接口：UADK.chat(ChatRequest request, ChatCallback callback)

请求参数（ChatRequest.Builder）：

返回（ChatResponse，字段详见第五章）：content（完整回答）/ reasoning（思考过程，可空）/ meta / usage / traceId / rawJson。

import com.umeng.adk.*;
import java.util.ArrayList;
import java.util.List;

List<Message> messages = new ArrayList<>();
messages.add(new Message("user", "你好，请介绍一下自己"));

ChatRequest request = new ChatRequest.Builder()
        .model("auto")
        .messages(messages)
        .build();

UADK.chat(request, new ChatCallback() {
    @Override
    public void onSuccess(ChatResponse response) {
        String answer = response.getContent();
        String reasoning = response.getReasoning(); // 思考过程，可能为 null
        UsageInfo usage = response.getUsage();
        runOnUiThread(() -> textView.setText(answer));
    }

    @Override
    public void onError(UADKError error) {
        runOnUiThread(() -> showError(error.getMessage()));
    }
});

4.2 流式聊天（SSE）

接口：UADK.chatStream(ChatRequest request, StreamCallback callback)

请求参数：与 4.1 完全一致（同一个 ChatRequest，见 4.1 参数表）。

回调参数说明（StreamCallback 四方法）：

import com.umeng.adk.*;
import java.util.ArrayList;
import java.util.List;

List<Message> messages = new ArrayList<>();
messages.add(new Message("user", "写一首关于春天的诗"));

ChatRequest request = new ChatRequest.Builder()
        .model("auto")
        .messages(messages)
        .enableThinking(true) // 开启深度思考
        .build();

final StringBuilder contentBuilder = new StringBuilder();

UADK.chatStream(request, new StreamCallback() {
    @Override
    public void onMeta(MetaInfo meta) {
        // 首个事件，获取 sessionId 用于多轮会话
        String sessionId = meta.getSessionId();
    }

    @Override
    public void onDelta(DeltaEvent delta) {
        if (DeltaEvent.TYPE_CONTENT.equals(delta.getType())) {
            contentBuilder.append(delta.getDelta());
            runOnUiThread(() -> textView.setText(contentBuilder.toString()));
        } else if (DeltaEvent.TYPE_REASONING.equals(delta.getType())) {
            // 思考过程增量
        }
    }

    @Override
    public void onDone(UsageInfo usage) {
        // 流式完成，获取用量
        long totalTokens = usage.getTotalTokens();
    }

    @Override
    public void onError(UADKError error) {
        runOnUiThread(() -> showError(error.getMessage()));
    }
});

4.3 文生图

文生图与文本生成同一入口，须通过流式接口 chatStream 调用，模型须为 modelType = image_generation 的模型（经 listModels 动态获取，禁止硬编码模型名）。

请求参数：同 4.1 ChatRequest（model 传 image_generation 模型的 displayName），其中 imageParams 子参数如下：

返回：图链经 onDelta 以 type=content 整段 Markdown 一次性下发（形如 ![生成图片1](<oss-url>)）。

import com.umeng.adk.*;
import java.util.Collections;

List<Message> messages = Collections.singletonList(
        new Message("user", "一只在滑雪的柴犬"));

ChatRequest request = new ChatRequest.Builder()
        .model("<经 listModels 获取的 image_generation 模型 displayName>")
        .messages(messages)
        .imageParams(new ImageParams("1024x1024", "medium", 1))
        .build();

UADK.chatStream(request, new StreamCallback() {
    @Override
    public void onMeta(MetaInfo meta) { }

    @Override
    public void onDelta(DeltaEvent delta) {
        if (DeltaEvent.TYPE_CONTENT.equals(delta.getType())) {
            // 文生图图链以 type=content 返回，Markdown 格式: ![描述](图片URL)
            String markdownImage = delta.getDelta();
            // 解析 URL 后用 Glide 等图片库加载
        }
    }

    @Override
    public void onDone(UsageInfo usage) { }

    @Override
    public void onError(UADKError error) { }
});

4.4 模型列表

接口：UADK.listModels(ModelsCallback callback)

请求参数：无。

返回（List<ModelInfo>）：

列表顺序由服务端返回（auto 通常排首位）。

import com.umeng.adk.*;
import android.util.Log;

UADK.listModels(new ModelsCallback() {
    @Override
    public void onSuccess(List<ModelInfo> models) {
        for (ModelInfo model : models) {
            Log.d("Models", model.getDisplayName()
                    + " | type=" + model.getModelType()
                    + " | thinking=" + model.isSupportsThinking());
        }
    }

    @Override
    public void onError(UADKError error) {
        Log.e("Models", "获取模型列表失败: " + error.getMessage());
    }
});

4.5 多轮会话

import com.umeng.adk.*;
import java.util.Collections;

// 首轮：不传 sessionId
ChatRequest firstRequest = new ChatRequest.Builder()
        .model("auto")
        .messages(Collections.singletonList(new Message("user", "我叫小明")))
        .build();

// 保存 sessionId

final String[ ] savedSessionId = new String[1];


UADK.chatStream(firstRequest, new StreamCallback() {
    @Override
    public void onMeta(MetaInfo meta) {
        savedSessionId[0] = meta.getSessionId(); // 保存
    }

    @Override
    public void onDelta(DeltaEvent delta) { }

    @Override
    public void onDone(UsageInfo usage) {
        // 第二轮：携带 sessionId
        ChatRequest secondRequest = new ChatRequest.Builder()
                .model("auto")
                .messages(Collections.singletonList(new Message("user", "我叫什么？")))
                .sessionId(savedSessionId[0])
                .loadHistory(true)
                .build();

        UADK.chatStream(secondRequest, new StreamCallback() {
            @Override
            public void onMeta(MetaInfo meta) { }

            @Override
            public void onDelta(DeltaEvent delta) {
                // 模型将回答 "小明"
            }

            @Override
            public void onDone(UsageInfo usage) { }

            @Override
            public void onError(UADKError error) { }
        });
    }

    @Override
    public void onError(UADKError error) { }
});

4.6 七场景调用入口（text / nlp / translate / ocr / vision / asr / tts）

SDK 提供七个场景化调用入口，无需指定模型，场景参数由各 Request 构建器承载；回调在后台线程触发。

统一结果字段：七场景结果均继承 ScenarioResult 基类，公共字段：

子类便捷字段：TextResult.getContent()、NlpResult.getStructured()/getTokens()/getEntities()/getKeywords()、TranslateResult.getContent()/getDetectedLang()、OcrResult.getContent()/getStructured()、VisionResult.getStructured()、AsrResult.getContent()/getSentences()/getLanguage()、TtsResult.getAudioUrl()/getAudioData()/getDurationMs()（audioData 恒为 null）。

便捷入口——常用参数组合的简化构造：

⚠️ 当前版本限制：vision 场景按实测参考形态解析（见 4.7.5）；ocr 场景 structured.result 内部结构未定型，只消费 content（见 4.7.4）。

示例：翻译（便捷入口）

import com.umeng.adk.*;

TranslateRequest request = TranslateRequest.ofText("你好，世界", "en");
// 需要 sourceLang / domain 等可选参数时用 Builder：
// new TranslateRequest.Builder()
//         .messages(Collections.singletonList(Message.ofUser("你好，世界")))
//         .sourceLang("auto").targetLang("en").build();

UADK.translate(request, new UADKCallback<TranslateResult>() {
    @Override
    public void onSuccess(TranslateResult result) {
        Log.d("Scenario", "content=" + result.getContent()
                + ", detectedLang=" + result.getDetectedLang()
                + ", executedBy=" + result.getExecutedBy()
                + ", traceId=" + result.getTraceId());
    }

    @Override
    public void onError(UADKError error) {
        Log.e("Scenario", "翻译失败: " + error.getMessage());
    }
});

示例：语音合成（便捷入口）

TtsRequest ttsRequest = TtsRequest.ofText("你好，U-ADK");
// 需要 voice / format 等可选参数时用 Builder：
// new TtsRequest.Builder()
//         .messages(Collections.singletonList(Message.ofUser("你好，U-ADK")))
//         .voice("longxiaochun").format("mp3").build();

UADK.tts(ttsRequest, new UADKCallback<TtsResult>() {
    @Override
    public void onSuccess(TtsResult result) {
        Log.d("Scenario", "audioUrl=" + result.getAudioUrl()
                + ", durationMs=" + result.getDurationMs()
                + ", executedBy=" + result.getExecutedBy());
    }

    @Override
    public void onError(UADKError error) { }
});

媒体输入（ocr / vision / asr），两种形态二选一：

• 本地文件路径：imageFile(path) / audioFile(path)——SDK 自动完成素材上传；上传失败时通过 onError 返回错误。contentType(...) 参数无效，无需调用。

• 素材 URL：imageUrl(url) / audioUrl(url)——已持有素材 URL 时直接传入。

• 两种形态互斥（同时传入或均不传入 → 返回错误码 1001）。

4.7 七场景参数与返回明细

{
  "structured": {
    "tokens": [
      {"text": "友盟", "startOffset": 0, "endOffset": 2, "partOfSpeech": "NR"}
    ],
    "entities": [
      {"text": "友盟", "type": "ORG", "startOffset": 0, "endOffset": 2, "confidence": 0.98}
    ],
    "keywords": [
      {"text": "开发者数据服务", "score": 0.92}
    ]
  }
}

// FACE_DETECTION
{"task":"FACE_DETECTION","result":{"faces":[
  {"boundingBox":{"x":95,"y":0,"width":905,"height":999},"confidence":0.998}
]}}

// OBJECT_DETECTION
{"task":"OBJECT_DETECTION","result":{"objects":[
  {"bbox_2d":[28,254,723,894],"category":"laptop"},
  {"bbox_2d":[554,454,701,654],"category":"mug"}
]}}

// IMAGE_CLASSIFICATION
{"task":"IMAGE_CLASSIFICATION","result":{
  "category":"技术文档",
  "subcategories":["人工智能","边缘计算","云原生"],
  "confidence":0.95
}}

ChatRequest

Message

构造：new Message(role, content) / Message.ofUser(content)（后者构造用户消息，场景化调用推荐）。

ImageParams

ChatResponse

MetaInfo

DeltaEvent

类型常量：

UsageInfo

ModelInfo

UADKError

三个 ID 的语义分工

响应中可能出现三个不同层级的 ID，用途各不相同：

requestId 与 traceId 一次请求内同时返回：前者是业务单据号，后者是链路排查号。

6.1 UADKError 结构说明

所有错误路径统一收敛为 UADKError 对象，包含六个核心字段：

• sCode：服务端九位错误码（本地/网络错误时为 0）

• code：分类错误码

• message：可直接展示的错误描述

• source：错误来源枚举

• cause：原始异常引用（可选）

• traceId：服务端链路追踪 ID（本地/网络错误为 null）

6.2 Source 枚举含义

6.3 本地错误码

6.4 错误处理示例

@Override
public void onError(UADKError error) {
    switch (error.getSource()) {
        case LOCAL:
            // 本地校验不通过，检查调用时机和参数
            break;
        case NETWORK:
            // 网络异常，提示用户检查网络
            break;
        case GATEWAY:
            // 服务端业务错误，可通过 sCode 获取详细错误码
            long serverCode = error.getSCode();
            break;
        case SSE:
            // SSE 流中断错误
            break;
        case CREDENTIAL:
            // 凭证问题，可能需要重新初始化
            break;
    }
    Log.e("UADK", error.toString());
}

7.1 ADK SDK 内置规则

ADK 产物（Maven 制品 / 本地 AAR）自带 consumer-rules.pro，在接入方 App 开启混淆时自动生效：

# U-ADK consumer 混淆规则（随产物下发，在接入方 App 混淆时生效）
#
# 保证接入方开启混淆后，SDK 对外公开 API 不被移除或改名。


- keep public class com.umeng.adk.* {

    public *;
}

7.2 OkHttp 混淆规则

OkHttp 3.12.13 自带混淆规则，正常情况下无需额外配置。若遇到问题可补充：

-dontwarn okhttp3.**


-dontwarn okio.**


-keep class okhttp3.** { *; }


-keep interface okhttp3.** { *; }

7.3 完整 keep 规则参考

如果上述自动规则不生效（如自定义混淆工具链），可在 proguard-rules.pro 中手动添加：

# U-ADK SDK 公开 API

- keep public class com.umeng.adk.* {

    public *;
}

# OkHttp

-dontwarn okhttp3.**


-dontwarn okio.**


-keep class okhttp3.** { *; }


-keep interface okhttp3.** { *; }


# 友盟

-keep class com.umeng.** { *; }


-keep class org.repackage.** { *; }