快速找到所需文档，高效完成接入与排障

1.1 系统与工具

1.2 依赖库

1.3 权限清单

说明：INTERNET 和 GET_NETWORK_INFO 为系统级权限，在 module.json5 中声明即可生效。MICROPHONE 属于敏感权限，需在运行时动态申请。

2.1 ohpm 安装

ohpm install @umeng/common

2.2 配置 umconfig.json

在宿主 App 的 AppScope/resources/rawfile/ 目录下创建 umconfig.json：

{
  "appKey": "您的AppKey",
  "channel": "default"
}

2.3 AbilityStage 中初始化

在宿主 App 的 AbilityStage 入口文件中完成 Common SDK 初始化：

// MyAbilityStage.ets
import { AbilityStage } from '@kit.AbilityKit';
import { UMAbridge } from '@umeng/common';

export default class MyAbilityStage extends AbilityStage {
  onCreate() {
    // 1. 绑定上下文
    UMAbridge.getInstance().bindContext(this.context.getApplicationContext());
    // 2. 用户授权后调用 agree（隐私合规要求，详见 2.5）
    UMAbridge.getInstance().agree();
  }
}

在 entry 模块的 module.json5 中配置 srcEntry：

{
  "module": {
    "srcEntry": "./ets/MyAbilityStage.ets",
    // ... 其他配置
  }
}

2.4 初始化顺序约束

接入方须严格按照以下顺序完成初始化：

bindContext → agree → UADK.init → UADK.prepare → 业务调用

说明：UADK.init 内部依赖 Common SDK 提供的 UMID 进行鉴权。若 Common SDK 未完成 bindContext 和 agree，ADK 初始化将因鉴权信息缺失而失败。

2.5 隐私合规说明

agree() 表示终端用户已同意隐私政策。接入方须确保：

1. 在用户明确同意隐私政策后再调用 agree()

2. 在用户同意前，不得采集任何设备标识信息

3. bindContext() 可在同意前调用，但 agree() 必须在用户授权后触发

3.1 依赖引入

本地 HAR

将 ADK HAR 包放置于项目目录，在 oh-package.json5 中通过 file 协议引用：

{
  "dependencies": {
    "@umeng/adk": "file:./libs/adk-0.1.0.har"
  }
}

在线依赖

ohpm install @umeng/adk

安装后 oh-package.json5 自动写入依赖：

{
  "dependencies": {
    "@umeng/adk": "^0.1.0"
  }
}

3.2 初始化

调用 UADK.init 完成 SDK 初始化，随后调用 UADK.prepare 预加载端侧能力：

static init(context: Context, appKey: string, config?: ADKConfig): boolean

ADKConfig 参数表：

UADK.prepare() 为异步方法，返回 Promise<boolean>：

static async prepare(): Promise<boolean>

说明：prepare() 内部完成端侧模型加载与能力探测，调用耗时与设备性能相关。prepare() 幂等，重复调用安全返回。

完整初始化代码示例：

import { UADK } from '@umeng/adk';

// 在 EntryAbility.onCreate 中调用
async function initADK(context: Context): Promise<void> {
  const config = { logLevel: 'DEBUG' as const, timeoutMs: 30000 };
  const inited = UADK.init(context, 'YOUR_APP_KEY', config);
  if (!inited) {
    console.error('ADK init failed');
    return;
  }
  const ready = await UADK.prepare();
  if (ready) {
    console.info('ADK is ready');
  }
}

3.3 调试模式

接入方可通过 ADKConfig.logLevel 控制日志输出级别。开发调试阶段建议设置为 DEBUG，生产环境建议设置为 WARN 或 ERROR。

const config = { logLevel: 'DEBUG' as const };
UADK.init(context, appKey, config);

日志级别说明：

3.4 状态查询

接入方可通过以下属性查询 SDK 当前状态：

说明：建议在调用业务 API 前检查 UADK.isReady，避免在未就绪状态下发起调用导致 NOT_INITIALIZED 错误。

4.1 非流式聊天（Chat）

Chat 接口提供与后端大模型的直接对话能力，不走端云路由。

static async chat(request: ChatRequest): Promise<ChatResponse>

ChatRequest 参数表：

ChatResponse 返回字段表：

代码示例：

import { UADK, ChatRequest, ChatResponse } from '@umeng/adk';

const request: ChatRequest = {
  messages: [
    { role: 'user', content: '你好，请介绍一下你自己' }
  ],
  sessionId: 'session_001'
};

const response: ChatResponse = await UADK.chat(request);
console.info(`回复：${response.content}`);

4.2 模型列表

查询当前可用的模型列表：

static async listAdkModels(): Promise<AdkModelInfo[]>

import { UADK } from '@umeng/adk';

const models = await UADK.listAdkModels();
models.forEach(m => console.info(`${m.modelId}: ${m.modelName}`));

4.3 场景化能力（七场景）

ADK 提供七类场景化能力，每类场景均支持三种调用方式。

场景总览：

三种调用方式：

说明：推荐使用端云路由方式。SDK 内部根据设备 AI 芯片能力、模型加载状态与网络连接情况自动选择最优执行路径，接入方无需关心路由细节。

端云路由机制：

1. 检查端侧是否具备对应场景的推理能力

2. 若端侧可用且网络非必需，优先执行端侧推理

3. 若端侧不可用或推理失败，自动降级至云端

4. 降级原因通过 ScenarioResult.executedBy 与 ScenarioResult.error 反映

4.4 七场景参数与返回明细

import { UADK, AsrScenarioRequest, ScenarioResult } from '@umeng/adk';

// 端云路由
const request: AsrScenarioRequest = {
  audioFilePath: '/data/storage/audio/sample.wav',
  audioFormat: 'wav',
  sampleRate: 16000,
  languageHints: ['zh-CN']
};
const result: ScenarioResult = await UADK.asr(request);
console.info(`识别结果：${result.content}，执行方：${result.executedBy}`);

import { UADK, TtsScenarioRequest, ScenarioResult } from '@umeng/adk';

const request: TtsScenarioRequest = {
  text: '欢迎使用友盟 ADK',
  voice: 'default',
  format: 'mp3',
  speed: 1.0
};
const result: ScenarioResult = await UADK.tts(request);
if (result.audioUrl) {
  console.info(`音频路径：${result.audioUrl}`);
}

import { UADK, OcrScenarioRequest, ScenarioResult } from '@umeng/adk';

const request: OcrScenarioRequest = {
  imageFilePath: '/data/storage/images/sample.png'
};
const result: ScenarioResult = await UADK.ocr(request);
console.info(`识别文本：${result.content}`);

import { UADK, VisionScenarioRequest, ScenarioResult } from '@umeng/adk';

const request: VisionScenarioRequest = {
  imageFilePath: '/data/storage/images/photo.jpg',
  task: 'describe'
};
const result: ScenarioResult = await UADK.vision(request);
console.info(`图片描述：${result.content}`);

import { UADK, TextScenarioRequest, ScenarioResult } from '@umeng/adk';

const request: TextScenarioRequest = {
  text: '这是一段需要摘要的长文本内容...',
  task: 'summarize',
  maxLength: 100
};
const result: ScenarioResult = await UADK.text(request);
console.info(`摘要结果：${result.content}`);

import { UADK, NlpScenarioRequest, ScenarioResult } from '@umeng/adk';

const request: NlpScenarioRequest = {
  text: '北京是中国的首都',
  tasks: ['tokenization', 'ner'],
  language: 'zh-CN'
};
const result: ScenarioResult = await UADK.nlp(request);
console.info(`NLP 结果：${result.content}`);
if (result.structured) {
  console.info(`结构化：${JSON.stringify(result.structured)}`);
}

import { UADK, TranslateScenarioRequest, ScenarioResult } from '@umeng/adk';

const request: TranslateScenarioRequest = {
  text: 'Hello, how are you?',
  targetLang: 'zh-CN',
  sourceLang: 'en-US'
};
const result: ScenarioResult = await UADK.translate(request);
console.info(`翻译结果：${result.content}`);

5.1 ChatRequest

interface ChatRequest {
  model?: string;
  messages: Message[];
  sessionId?: string;
  enableThinking?: boolean;
  loadHistory?: boolean;
  imageParams?: ImageParams;
}

5.2 Message

interface Message {
  role: string;    // 'user' | 'assistant' | 'system'
  content: string;
}

5.3 ImageParams

interface ImageParams {
  size?: string;     // 图片尺寸，如 '1024x1024'
  quality?: string;  // 质量等级
  n?: number;        // 生成数量
}

5.4 ChatResponse

interface ChatResponse {
  meta: MetaInfo | null;
  content: string;
  reasoning: string | null;
  usage: UsageInfo | null;
  traceId: string;
  rawJson: string;
}

5.5 MetaInfo

interface MetaInfo {
  model: string;
  requestId: string;
}

5.6 UsageInfo

interface UsageInfo {
  inputTokens: number;
  outputTokens: number;
}

5.7 ScenarioResult

interface ScenarioResult {
  executedBy: ExecutedBy;                      // 恒有
  content: string;                              // 恒有
  structured: Record<string, Object> | null;    // 条件存在
  audioUrl: string | null;                      // 条件存在（仅 TTS）
  usage: UsageInfo | null;                      // 条件存在（仅云端）
  meta: MetaInfo | null;                        // 条件存在（仅云端）
  error: ADKError | null;                       // 条件存在
  rawJson: string;                              // 恒有
  traceId: string;                              // 恒有
}

5.8 ExecutedBy

type ExecutedBy = 'VENDOR' | 'CLOUD' | 'UNKNOWN';

5.9 ADKConfig

interface ADKConfig {
  logLevel?: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'NONE';
  timeoutMs?: number;
}

5.10 ADKError

class ADKError extends Error {
  readonly sCode: number;
  readonly code: ADKErrorCode;
  readonly source: ADKErrorSource;
  readonly traceId: string;
}

5.11 ADKErrorCode

enum ADKErrorCode {
  PARAM = 1001,
  NOT_INITIALIZED = 1002,
  DISABLED = 1003,
  NETWORK = 1004,
  CREDENTIAL = 1005,
  DEVICE_CAPABILITY_UNAVAILABLE = 1006,
  UNKNOWN = 9999
}

5.12 ADKErrorSource

enum ADKErrorSource {
  LOCAL = 'LOCAL',
  NETWORK = 'NETWORK',
  GATEWAY = 'GATEWAY',
  CREDENTIAL = 'CREDENTIAL'
}

5.13 各场景 ScenarioRequest

// ASR
interface AsrScenarioRequest {
  audioUrl?: string;
  audioFilePath?: string;
  audioFormat?: string;
  sampleRate?: number;
  languageHints?: string[];
  hotwords?: string[];
}

// TTS
interface TtsScenarioRequest {
  text: string;
  voice?: string;
  format?: string;
  sampleRate?: number;
  speed?: number;
}

// OCR
interface OcrScenarioRequest {
  imageUrl?: string;
  imageFilePath?: string;
  task?: string;
  languageHints?: string[];
}

// VISION
interface VisionScenarioRequest {
  imageUrl?: string;
  imageFilePath?: string;
  task?: string;
  options?: Record<string, Object>;
}

// TEXT
interface TextScenarioRequest {
  text: string;
  task?: string;
  prompt?: string;
  maxLength?: number;
  style?: string;
  language?: string;
}

// NLP
interface NlpScenarioRequest {
  text: string;
  task?: string;
  tasks?: string[];
  language?: string;
}

// TRANSLATE
interface TranslateScenarioRequest {
  text: string;
  targetLang: string;
  sourceLang?: string;
  domain?: string;
}

6.1 ADKError 结构说明

ADK 所有异步操作失败时均抛出 ADKError，包含以下核心字段：

6.2 ADKErrorSource 枚举含义

6.3 本地错误码表

6.4 错误处理示例

import { UADK, ADKError, TextScenarioRequest } from '@umeng/adk';

try {
  const result = await UADK.text({ text: '测试文本', task: 'summarize' });
  if (result.error) {
    // 执行层错误，通过 ScenarioResult.error 返回
    console.warn(`执行失败：${result.error.code} - ${result.error.message}`);
  } else {
    console.info(`结果：${result.content}`);
  }
} catch (e) {
  // 抛出层错误（如未初始化、参数校验）
  if (e instanceof ADKError) {
    console.error(`ADK 错误：[${e.code}] ${e.message}，来源：${e.source}，traceId：${e.traceId}`);
    if (e.sCode === 1002) {
      // 未初始化，引导初始化流程
      console.error('请先调用 UADK.init 和 UADK.prepare');
    }
  }
}

7.1 module.json5 权限声明

在 entry 模块的 module.json5 中声明所需权限：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO"
      },
      {
        "name": "ohos.permission.MICROPHONE",
        "reason": "$string:microphone_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

说明：MICROPHONE 权限仅在接入方使用 ASR 场景时需要声明。reason 字段需在 string.json 中配置对应的多语言文案。

7.2 混淆配置

若宿主 App 开启了代码混淆，须将 ADK 相关类加入保留列表。在 consumer-rules.pro 或 obfuscation-rules.pro 中添加：

# ADK SDK
-keep class UADK { *; }
-keep class ADKError { *; }
-keep class ADKConfig { *; }
-keep class ScenarioResult { *; }
-keep class ChatRequest { *; }
-keep class ChatResponse { *; }

在 build-profile.json5 中配置混淆规则文件：

{
  "app": {
    "products": [
      {
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true
          }
        }
      }
    ]
  }
}

7.3 签名配置

HarmonyOS 应用发布需要签名配置。签名材料（.p12 证书与 .p7b 描述文件）在 DevEco Studio 中通过 File > Project Structure > Signing Configs 配置。

若使用自动签名，DevEco Studio 将自动管理证书与描述文件。若使用手动签名，接入方须自行申请并配置签名材料。

说明：签名配置异常（如证书过期、描述文件不匹配）将导致构建失败，详见 FAQ-1。

FAQ-1：DevEco Studio 构建报错签名材料非法

现象：构建时出现 "The signing material is invalid" 或类似错误。

原因：签名证书过期、描述文件与 BundleName 不匹配，或签名密码错误。

处理建议：

1. 检查证书有效期，若已过期则重新申请

2. 确认描述文件中的 BundleName 与项目 AppScope/app.json5 中一致

3. 若使用自动签名，尝试 File > Project Structure > Signing Configs 中勾选 "Automatically generate signature" 重新生成

4. 清理构建缓存：Build > Clean Project，重新构建

FAQ-2：初始化 prepare 回调 1004（zid 不能为 null）

现象：UADK.prepare() 返回失败，错误码 1004，日志中出现 "zid cannot be null"。

原因：Common SDK 未完成初始化，UMID（设备标识）采集失败，导致 ADK 鉴权请求中 zid 字段为空。

处理建议：

1. 确认 MyAbilityStage 中已调用 UMAbridge.getInstance().bindContext(context)

2. 确认已在用户授权后调用 UMAbridge.getInstance().agree()

3. 确认 umconfig.json 已正确放置于 AppScope/resources/rawfile/ 目录，且 appKey 格式正确（24 位十六进制）

4. 检查网络连接，UMID 采集需要首次联网上报

FAQ-3：端侧能力全部走了云端（FALLBACK_ROUTE）

现象：调用 UADK.xxxVendor() 返回错误，或 UADK.xxx() 的 executedBy 始终为 CLOUD。

原因：设备不具备对应场景的端侧推理能力，或端侧模型加载失败。

处理建议：

1. 检查设备是否支持目标场景的端侧推理（并非所有 HarmonyOS 设备均配备 AI 芯片）

2. 调用 UADK.isReady 确认 prepare 已完成

3. 查看日志中是否有模型加载失败的 WARN 级别日志

4. 对于不具备端侧能力的设备，建议直接使用 UADK.xxxCloud() 避免不必要的端侧探测开销

5. 端云路由模式下 FALLBACK_ROUTE 为正常行为，SDK 已自动降级至云端，不影响功能使用