ailia LLMのAPIの概要

基本的な使用方法

ailia LLMの使用例です。

#include "ailia_llm.h"
 
int main(int argc, char *argv[]){
    struct AILIALLM* llm;
    unsigned int n_ctx = 8192;
    ailiaLLMCreate(&llm);
    ailiaLLMOpenModelFileA(llm, "../models/gemma-2-2b-it-Q4_K_M.gguf", n_ctx);
 
    std::vector<AILIALLMChatMessage> messages;
    AILIALLMChatMessage message;
 
    message.role = "system";
    message.content = "語尾に「くま」をつけて回答してください。";
    messages.push_back(message);
 
    message.role = "user";
    message.content = "こんにちは。";
    messages.push_back(message);
 
    ailiaLLMSetPrompt(llm, &messages[0], messages.size());
 
    std::string text = "";
    while(true) {
        unsigned int done = 0;
        int status = ailiaLLMGenerate(llm, &done);
        if (done == 1 || status != AILIA_LLM_STATUS_SUCCESS){
            break;
        }
        unsigned int size = 0;
        ailiaLLMGetDeltaTextSize(llm, &size);
        std::vector<char> delta(size);
        ailiaLLMGetDeltaText(llm, &delta[0], delta.size());
        text = text + std::string(&delta[0]);
    }
 
    ailiaLLMDestroy(llm);
 
    return 0;
}

画像入力（VLM）

画像対応のTextモデルと対応するmmprojを用意します。ailiaLLMCreate → ailiaLLMOpenModelFileA → ailiaLLMOpenMultimodalProjectorFileA の順に呼び、 ailiaLLMGetMultimodalCapabilities の vision_support を確認してください。 <__media__> は media_data の各要素と出現順・個数を一致させます。

/* llm: text model and matching vision-capable projector already opened. */
int set_image_prompt(struct AILIALLM *llm, const char *image_path) {
    unsigned int vision = 0, audio = 0;
    int status = ailiaLLMGetMultimodalCapabilities(llm, &vision, &audio);
    if (status != AILIA_LLM_STATUS_SUCCESS) return status;
    if (!vision || !image_path) return AILIA_LLM_STATUS_INVALID_ARGUMENT;
 
    AILIALLMMediaData media = {0};
    media.media_type = "image";
    media.file_path = image_path; /* UTF-8 local image path */
    AILIALLMMultimodalChatMessage message = {0};
    message.role = "user";
    message.content = "この画像を説明してください: <__media__>";
    message.media_data = &media;
    message.media_count = 1;
    return ailiaLLMSetMultimodalPrompt(llm, &message, 1);
}

成功後は基本例と同じ生成APIでテキストを取得します。画像はファイルパスのほか、エンコード済み画像バッファ（data / data_size、width=height=0）または Raw RGB（width * height * 3 バイト）を渡せます。

音声入力（ALM）

音声認識・音声内容への質問には、音声入力に対応するTextモデルと、そのモデルに対応した音声encoder入りmmprojが必要です。画像専用mmprojでは音声を処理できません。対応する機能・言語はモデルに依存します。音声合成・音声出力には対応していません。

ailiaLLMCreate 後、ailiaLLMOpenModelFileA でTextモデルを開きます。
ailiaLLMOpenMultimodalProjectorFileA で対応するmmprojを開きます。
ailiaLLMGetMultimodalCapabilities の audio_support が非0であることを確認します。
以下の例で音声promptを設定します。
成功後は基本例と同じ ailiaLLMGenerate、 ailiaLLMGetDeltaTextSize、ailiaLLMGetDeltaText でテキストを取得します。各APIの戻り値を確認し、失敗時は ailiaLLMGetErrorDetail を参照してください。

#include "ailia_llm.h"
 
/* llm: text model and matching audio-capable projector already opened. */
int set_audio_prompt(struct AILIALLM *llm, const char *audio_path) {
    unsigned int vision = 0, audio = 0;
    int status = ailiaLLMGetMultimodalCapabilities(llm, &vision, &audio);
    if (status != AILIA_LLM_STATUS_SUCCESS) return status;
    if (!audio || !audio_path) return AILIA_LLM_STATUS_INVALID_ARGUMENT;
 
    AILIALLMMediaData media = {0};
    media.media_type = "audio";
    media.file_path = audio_path; /* UTF-8 WAV/MP3/FLAC path */
    /* data=NULL, data_size=0, width=0, height=0 */
 
    AILIALLMMultimodalChatMessage message = {0};
    message.role = "user";
    message.content = "Transcribe this audio: <__media__>";
    message.media_data = &media;
    message.media_count = 1;
    return ailiaLLMSetMultimodalPrompt(llm, &message, 1);
}

音声はWAV/MP3/FLACのファイルパス、またはエンコード済みファイルのバッファを渡します。バッファ入力では file_path=NULL、data と data_size を設定します。 data がある場合はパスより優先されます。data_size はunsigned intに収まるサイズを使い、呼出しが完了するまでバッファと文字列を保持してください。音声の width と height は必ず0です。Raw PCMやマイクの逐次入力APIではありません。 <__media__> とメディア配列は順序・個数を一致させます。

Android QNNでの音声入力

事前コンパイル済みText .qnn と、音声context・CPU用weightを含むmmproj .qnn を上記のモデルopen APIへ渡せます。元のGGUFを端末へ配置する必要はありません。 SoCに一致するモデルとQNNライブラリ、本体と同じビルドのQNN pluginを使用してください。古い画像専用 .qnn を読み込んでも音声機能は追加されません。

特徴抽出とsubsamplingはCPU、全12 Conformer層と最終射影は単一HTPグラフで実行します。短音声のパディングと長音声の履歴付き分割はランタイムが処理します。旧linear版の音声packageは、現在のコンパイラで再生成してください。音声と画像を一つのpromptに混在させることはできません。別のpromptとして実行してください。音声入力時は以前のpromptのKVを再利用しません。音声tokenはcausalに処理するため、 AR256を跨ぐ入力も可能ですが、音声から生成されたtoken列はモデルのcontext容量内に収める必要があります。音声入りpackageのQNN linear weightにはCPU fallbackを使えません。

Android QNNモデル

QNN対応ビルドでは、端末に合う事前コンパイル済みのText .qnn を ailiaLLMOpenModelFileA に渡します。VLM/ALMには同じモデル向けの projector .qnn を ailiaLLMOpenMultimodalProjectorFileA に渡します。 GGUFと異なり .qnn はSoC固有です。モデルとprojectorの組み合わせ、 QNNランタイム・pluginのバージョンを揃えてください。バックエンド未選択なら<tt>.qnnはHTP (QNN)へ自動振り分けされます。明示選択する場合は、CPU/GPUで.qnnを、HTP (QNN)でGGUFを開けません。

const char *stem = NULL;
int status = ailiaLLMGetQNNModelName(&stem); /* e.g. "sm7635" */
if (status != AILIA_LLM_STATUS_SUCCESS) return status;
/* 実際の配布ファイル名にはモデル名などの接頭辞が付く場合があります。
   stemとSoCが一致するText/Projectorパッケージを選択してください。 */
status = ailiaLLMOpenModelFileA(llm, text_qnn_path, 0);
if (status != AILIA_LLM_STATUS_SUCCESS) return status;
status = ailiaLLMOpenMultimodalProjectorFileA(llm, mmproj_qnn_path);
if (status != AILIA_LLM_STATUS_SUCCESS) return status;

Textだけを使う場合、projectorを開く必要はありません。n_ctx=0 はpackageのコンテキスト長を使用します。非QNNビルドやplugin不在ではモデル名取得は UNIMPLEMENTED、未対応SoCでは OTHER_ERROR を返します。失敗の詳細は ailiaLLMGetErrorDetail で確認できます。

Tool Use（JSON API）

Tool Useでは最初のuserメッセージからailiaLLMSetPromptJsonを使用します。 ailiaLLMSetToolsでツールが設定されている間、従来のailiaLLMSetPromptとailiaLLMSetMultimodalPromptは AILIA_LLM_STATUS_INVALID_STATEを返します。ツールを解除すると再び利用できます。

ailiaLLMSetToolsにOpenAI互換のツール定義配列を渡します。
ailiaLLMSetPromptJsonにmessages配列そのもの（UTF-8 JSON）を渡します。
ailiaLLMGenerateを完了まで呼び出します。deltaはailiaLLMGetDeltaTextでプレビューできますが、取得・連結は必須ではありません。
ailiaLLMGetResponseJsonSize / ailiaLLMGetResponseJsonで構造化assistant JSONを取得します。
成功したオブジェクトをそのまま履歴に追加し、tool_callsがあれば実行して、ID付きのtool結果を追加し、次のプロンプトを設定します。

SDKが生成結果を蓄積するので、生の出力をアプリ側で引き回す必要はありません。 GetResponseJsonは読み取りで蓄積を消去しません。新しいプロンプトでリセットします。

例えばツール定義と最初の入力は次の形式です。ツールの実行はアプリ側で行い、モデルから返された名前・引数を検証してから呼び出してください。

[{"type":"function","function":{"name":"get_weather","description":"都市の天気を取得する","parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}]

[{"role":"user","content":"東京の天気は？"}]

/* llm: モデルを開いた状態。tools_json/messages_jsonには上記のJSON文字列を渡す。 */
int run_tool_turn(struct AILIALLM *llm, const char *tools_json,
                  const char *messages_json, char **response) {
    int status = ailiaLLMSetTools(llm, tools_json);
    if (status != AILIA_LLM_STATUS_SUCCESS) return status;
    status = ailiaLLMSetPromptJson(llm, messages_json);
    if (status != AILIA_LLM_STATUS_SUCCESS) return status;
    unsigned int done = 0;
    while (!done) {
        status = ailiaLLMGenerate(llm, &done);
        if (status != AILIA_LLM_STATUS_SUCCESS) return status;
    }
    unsigned int size = 0;
    status = ailiaLLMGetResponseJsonSize(llm, &size);
    if (status != AILIA_LLM_STATUS_SUCCESS) return status;
    *response = (char *)malloc(size); /* 呼び出し側でfreeする */
    if (!*response) return AILIA_LLM_STATUS_OTHER_ERROR;
    status = ailiaLLMGetResponseJson(llm, *response, size);
    if (status != AILIA_LLM_STATUS_SUCCESS) { free(*response); *response = NULL; }
    return status;
}

この例では <stdlib.h> をincludeし、response は有効な char ** とします。

JSON履歴

[
  {"role":"user","content":"東京の天気は？"},
  {"role":"assistant","content":"","tool_calls":[
    {"id":"call_0","type":"function","function":{
      "name":"get_weather","arguments":"{\"city\":\"東京\"}"}}
  ]},
  {"role":"tool","tool_call_id":"call_0","content":"雪、-3度"}
]

本文をツール構文として再解析しません。assistantのThinkingはreasoning_contentに指定します。 argumentsはJSONオブジェクトを表す**文字列**です。呼び出しのid/nameは空にできず、IDはassistant内で一意です。別ターンではIDを再利用できます。連続するtool結果は直前のassistantの呼び出しにIDで対応付けます。結果の順序は問いません。不明なID、重複結果、矛盾するツール名はINVALID_ARGUMENTです。ツール結果のcontentには文字列を指定し、オブジェクトはJSON文字列に変換してください。

画像・音声

対応するprojectorをailiaLLMOpenMultimodalProjectorFileAで読み込んだ後、userのcontent配列に順番に指定します。メディアはtoolsの有無にかかわらずJSONで入力できます。

[{"role":"user","content":[
  {"type":"text","text":"この画像と音声について説明してください。"},
  {"type":"image","file_path":"/path/to/image.jpg"},
  {"type":"audio","file_path":"/path/to/audio.wav"}
]}]

image/audioはfile_pathまたはdataをちょうど1つ指定します。dataは標準Base64（パディング付き）でエンコードしたファイル内容です。JPEG/PNG、WAV/MP3/FLAC等を使用できます。URL取得、動画、生RGB/PCMには対応しません。画像・音声を含む履歴は毎回再評価します。メディア非対応のモデル/projectorや未読込はINVALID_STATEです。画像と音声の対応状況はailiaLLMGetMultimodalCapabilitiesで確認できます。

不完全な出力・エラー

GetResponseJson：生成完了後に呼び出してください。未完了tool call/ThinkingはPARSE_ERRORです。部分結果を実行したり、引数を補完したりしません。
SetPromptJson：不完全なarguments、不正なJSON・型・ID対応、空配列はINVALID_ARGUMENTです。自動切り捨ては行いません。
再試行：GetResponseJsonがPARSE_ERRORの場合、失敗したassistantを追加せず、既存履歴に再試行を指示するuserメッセージを追加します。部分的な本文・Thinkingの取得は不要です。不完全な呼び出しのtool結果は作りません。
GetResponseJsonはプロンプト未設定、tools/Thinking変更後にINVALID_STATEを返します。プロンプト設定後・生成前の空出力は空のassistantです。
ファイル読込失敗はERROR_FILE_API、Base64からのデコード済みメディア読込失敗はERROR_BUFFER_API、不正なBase64はINVALID_ARGUMENTです。

SetTools(NULL)でツールを解除した後も、過去のtool_callsとtool結果をSetPromptJsonへ渡して要約・最終回答を生成できます。解除すると出力パーサーが無効になるため、結果JSONは解除前に取得してください。例外時もツール設定を解除するにはfinallyを使用してください。