Llama Stack 客户端 Kotlin API 库

我们很高兴分享一份 Kotlin 库的指南，它将 Llama Stack 的优势带到您的 Android 设备上。该库是一套 SDK，提供了一种简单有效的方式，将 AI 能力集成到您的 Android 应用中，无论是本地（设备上）还是远程推理。

功能特性

本地推理：纯设备上运行 Llama 模型，进行实时处理。我们目前使用 ExecuTorch 作为本地推理分发器，未来可能会支持其他分发器。
- ExecuTorch 是 PyTorch 框架内的一个完整的端到端解决方案，用于在设备上进行推理，具有高度的可移植性和无缝的性能。
远程推理：通过托管在远程连接（或无服务器 localhost）上的 Llama 模型进行远程推理任务。
简单集成：通过易于使用的 API，开发人员可以快速将 Llama Stack 集成到他们的 Android 应用中。本地与远程推理的差异也非常小。

最新发布说明：链接

带标签的发布是项目的稳定版本。虽然我们努力保持主分支的稳定，但不能保证没有 bug 或问题。

Android 演示应用

请查看我们的演示应用，了解如何将 Llama Stack 集成到您的 Android 应用中：Android 演示应用

应用中的关键文件是 ExampleLlamaStackLocalInference.kt、ExampleLlamaStackRemoteInference.kts 和 MainActivity.java。通过包含的业务逻辑，应用展示了如何在这两种环境下使用 Llama Stack。

快速入门

添加依赖

Kotlin 库

在您的 build.gradle.kts 文件中添加以下依赖

dependencies {
 implementation("com.llama.llamastack:llama-stack-client-kotlin:0.2.2")
}

这将把 jar 文件下载到您的 gradle 缓存中，路径类似于 ~/.gradle/caches/modules-2/files-2.1/com.llama.llamastack/

如果您打算进行远程推理，这足以开始。

本地依赖

对于本地推理，必须在您的应用中包含 ExecuTorch 库。

包含 ExecuTorch 库的方法如下：

从 llama-stack-client-kotlin-client-local 目录下载 download-prebuilt-et-lib.sh 脚本文件到您的本地机器。
将脚本移动到您的 Android 应用的顶层目录，即 app 目录所在的位置。
运行 sh download-prebuilt-et-lib.sh 以创建 app/libs 目录并将 executorch.aar 下载到该路径。这将为 XNNPACK delegate 生成一个 ExecuTorch 库。
在您的 build.gradle.kts 文件中添加 executorch.aar 依赖

dependencies {
  ...
  implementation(files("libs/executorch.aar"))
  ...
}

有关 Android 应用中本地 RAG 的其他依赖，请参阅 README。

在您的 Android 应用中使用 Llama Stack API

本节将分解演示应用，展示使用 Kotlin 库初始化和运行 Llama Stack 推理的核心部分。

设置远程推理

在 localhost 上启动 Llama Stack 服务器。以下是如何使用 firework.ai 发行版进行此操作的示例

conda create -n stack-fireworks python=3.10
conda activate stack-fireworks
pip install --no-cache llama-stack==0.2.2
llama stack build --template fireworks --image-type conda
export FIREWORKS_API_KEY=<SOME_KEY>
llama stack run fireworks --port 5050

确保 Llama Stack 服务器版本与 Kotlin SDK 库版本一致，以获得最大的兼容性。

其他推理提供商：表格

如何在演示应用中设置远程 localhost：设置

初始化客户端

客户端充当与特定推理类型及其关联参数交互的主要接口。只有在客户端初始化后，您才能配置并启动推理。

本地推理

远程推理

client = LlamaStackClientLocalClient
                    .builder()
                    .modelPath(modelPath)
                    .tokenizerPath(tokenizerPath)
                    .temperature(temperature)
                    .build()

// remoteURL is a string like "http://localhost:5050"
client = LlamaStackClientOkHttpClient
                .builder()
                .baseUrl(remoteURL)
                .build()

运行推理

借助 Kotlin 库管理所有主要操作逻辑，对于本地或远程的简单聊天推理，代码改动最小甚至没有。

val result = client!!.inference().chatCompletion(
            InferenceChatCompletionParams.builder()
                .modelId(modelName)
                .messages(listOfMessages)
                .build()
        )

// response contains string with response from model
var response = result.asChatCompletionResponse().completionMessage().content().string();

[仅限远程] 对于带有流式响应的推理

val result = client!!.inference().chatCompletionStreaming(
            InferenceChatCompletionParams.builder()
                .modelId(modelName)
                .messages(listOfMessages)
                .build()
        )

// Response can be received as a asChatCompletionResponseStreamChunk as part of a callback.
// See Android demo app for a detailed implementation example.

设置自定义工具调用

更多详情请参见 Android 演示应用：自定义工具调用

高级用户

本节旨在与希望深入了解 Llama Stack Kotlin 库的用户分享更多细节。无论您是对为开源库贡献、调试还是只是想了解更多，本节都适合您！

先决条件

您必须完成以下步骤

克隆仓库 (git clone https://github.com/meta-llama/llama-stack-client-kotlin.git -b latest-release)
将适当的 ExecuTorch 库移植到您的 Llama Stack Kotlin 库环境中。

cd llama-stack-client-kotlin-client-local
sh download-prebuilt-et-lib.sh --unzip

现在您会注意到，来自 executorch.aar 文件的 jni/、libs/ 和 AndroidManifest.xml 文件出现在本地模块中。这样本地客户端模块将能够识别 ExecuTorch SDK。

为开发/调试构建

如果您想通过开发、调试或在库中添加各种打印语句来贡献 Kotlin 库，请在 llama-stack-client-kotlin 目录下的终端中运行以下命令。

sh build-libs.sh

输出：.jar 文件位于 build-jars 目录中

将 .jar 文件复制到您的 Android 应用中的 lib 目录。同时确保在您的应用（或如果您正在使用演示应用）的 build.gradle.kts 文件中删除 llama-stack-client-kotlin 依赖，以避免有多个 llama stack 客户端依赖。

本地推理的其他选项

目前我们为本地推理提供额外的属性支持。为了获取每次推理调用的 tokens/sec 指标，请在您的 Android 应用中运行您的 chatCompletion 推理函数后添加以下代码。参考应用也有此实现

var tps = (result.asChatCompletionResponse()._additionalProperties()["tps"] as JsonNumber).value as Float

我们将来会添加更多属性。

远程推理的其他选项

网络选项

重试

遇到某些错误的请求默认会自动重试 2 次，并带有短暂的指数退避。连接错误（例如，由于网络连接问题）、408 Request Timeout、409 Conflict、429 Rate Limit 以及 >=500 Internal errors 默认都会重试。您可以在客户端构建器上提供 maxRetries 来配置此项。

val client = LlamaStackClientOkHttpClient.builder()
    .fromEnv()
    .maxRetries(4)
    .build()

超时

请求默认在 1 分钟后超时。您可以在客户端构建器上配置此项。

val client = LlamaStackClientOkHttpClient.builder()
    .fromEnv()
    .timeout(Duration.ofSeconds(30))
    .build()

代理

请求可以通过代理路由。您可以在客户端构建器上配置此项。

val client = LlamaStackClientOkHttpClient.builder()
    .fromEnv()
    .proxy(new Proxy(
        Type.HTTP,
        new InetSocketAddress("proxy.com", 8080)
    ))
    .build()

环境

请求默认发送到生产环境。您可以通过客户端构建器连接到其他环境，例如 sandbox。

val client = LlamaStackClientOkHttpClient.builder()
    .fromEnv()
    .sandbox()
    .build()

错误处理

此库在一个层次结构中抛出异常，便于处理。

LlamaStackClientException - 所有异常的基类。

LlamaStackClientServiceException - HTTP 错误，带有格式良好的响应体，我们能够解析。异常消息和 .debuggingRequestId() 将由服务器设置。

400	BadRequestException
401	AuthenticationException
403	PermissionDeniedException
404	NotFoundException
422	UnprocessableEntityException
429	RateLimitException
5xx	InternalServerException
其他	UnexpectedStatusCodeException

LlamaStackClientIoException - I/O 网络错误
LlamaStackClientInvalidDataException - 客户端的其他任何异常，例如：
- 我们未能序列化请求体
- 我们未能解析响应体（可访问响应码和响应体）

报告问题

如果您在使用本指南时遇到任何错误或问题，请在我们的 Github issue tracker 上提交错误/问题。

已知问题

我们已知以下问题并正在努力解决：

流式响应是本地和远程推理的正在进行中的工作。
由于 #1，目前不支持代理。Llama Stack 代理仅在流式模式下工作。
切换到其他模型是本地和远程平台的正在进行中的工作。

感谢

我们感谢 ExecuTorch 团队在我们集成 ExecuTorch 作为 Llama Stack 本地推理分发器之一时提供的支持。有关更多信息，请访问 ExecuTorch Github 仓库。

API 接口是使用 OpenAPI 标准通过 Stainless 生成的。