代码全由 AI 修改生成。

基于 Google AI Edge Gallery 修改的 Android 项目。这个版本把 App 内的本地 LLM 推理能力扩展为可由本机或局域网客户端调用的 OpenAI 兼容 API 服务。

• 上游项目：google-ai-edge/gallery
• 当前仓库：bugroom/google-ai-edge-gallery-local-api
• API 调试助手：bugroom/local-api-debug-helper
• 构建手册：BUILD_MANUAL.md

• 当前状态
• 功能概览
• 快速开始
• API 手册
• 构建说明
• GitHub Actions 工作流适配
• 故障排查
• 当前限制
• 项目文档
• 变更记录
• License

• Release APK 已可构建通过。
• Android 最低版本为 Android 9.0，minSdk = 28。
• 模型下载源保持官方 Hugging Face 源。
• 本地 API Server 已独立为侧栏入口。
• OpenAI 兼容接口已接入 LiteRT-LM 推理链路。
• 已支持默认模型、采样参数、API Key 和 CPU/GPU/NPU/TPU 推理后端配置。
• 流式响应已支持 SSE chunk、客户端断开处理和 data: [DONE] 结束事件。
• 本地 API 相关日志统一使用 LOCAL_API 标记。

• minSdk 从 31 调整为 28，支持 Android 9.0 及以上设备。
• 新增 ApiCompatibilityHelper 处理部分 Android API 版本兼容逻辑。
• 主题切换已兼容 Android 12 以下设备。
• Release 构建限制 arm64-v8a，降低 APK 体积。
• 配置弹窗数值滑块兼容 Int、Float、Double 等类型。
• API 服务由应用进程级 ApiServerManager 持有，离开 API Server 页面后继续运行。

• 新增 values-zh/strings.xml 中文资源。
• 保留英文资源，构建时包含 en 和 zh。

• 模型下载源保留官方 Hugging Face 源。
• 新增 HTTP 下载日志能力。
• 新增日志查看页面，支持复制日志用于排查问题。

• 入口：侧栏 -> API Server。
• HTTP 服务实现：native ServerSocket。
• 认证方式：无认证或 API Key。
• 认证头：Authorization: Bearer <apiKey>。
• 网络支持：本机访问和局域网访问。
• CORS：已支持跨域请求。
• 模型来源：已下载的 LLM 模型。
• 推理链路：复用现有 LiteRT-LM 运行时。

本地 API 相关日志统一使用 LOCAL_API，常见字段如下：

# Filter local API logs
adb logcat | grep LOCAL_API

1. 安装并打开 App。
2. 下载一个支持 LLM 的模型，例如 Gemma 或 Qwen。
3. 从侧栏进入 API Server。
4. 选择默认模型。
5. 配置默认采样参数和推理后端。
6. 配置监听地址和端口。
7. 局域网访问场景将 Host 设置为 0.0.0.0。
8. 按需启用 API Key 并复制 Key。
9. 打开 API 服务开关。
10. 使用 /health 或 /v1/models 验证服务。

局域网访问时，手机和客户端设备需要位于同一网络。Host 设置为 0.0.0.0 后，客户端应访问手机的局域网 IP。

可使用独立调试工具 local-api-debug-helper 验证 /health、/v1/models 和 /v1/chat/completions，支持非流式与流式响应测试。

curl http://127.0.0.1:8080/health

响应示例：

{
  "status": "ok",
  "uptime": 12345,
  "connections": 1,
  "loaded_model": null
}

无认证：

curl http://127.0.0.1:8080/v1/models

带 API Key 认证：

curl http://127.0.0.1:8080/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例：

{
  "object": "list",
  "data": [
    {
      "id": "Qwen2.5-1.5B-Instruct",
      "object": "model",
      "owned_by": "litert-community",
      "created": 1780680000
    }
  ]
}

非流式请求：

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "Qwen2.5-1.5B-Instruct",
    "messages": [
      {"role": "user", "content": "你好"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "top_p": 0.95,
    "top_k": 40,
    "accelerator": "GPU",
    "vision_accelerator": "GPU"
  }'

响应示例：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1780680000,
  "model": "Qwen2.5-1.5B-Instruct",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！很高兴为你服务。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2,
    "completion_tokens": 50,
    "total_tokens": 52
  }
}

请求参数：

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "Qwen2.5-1.5B-Instruct",
    "messages": [
      {"role": "user", "content": "讲个故事"}
    ],
    "stream": true
  }'

流式响应使用 Server-Sent Events 格式：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"你好"}}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"！"}}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":""},"finish_reason":"stop"}]}

data: [DONE]

客户端应累积每个 chunk 的 choices[0].delta.content。服务端正常结束时会发送 data: [DONE]。

Android 工程目录：

# Enter Android project
cd Android/src

编译 Kotlin：

# Compile release Kotlin sources
./gradlew :app:compileReleaseKotlin

构建 Release APK：

# Build release APK
./gradlew :app:assembleRelease

APK 输出路径：

Android/src/app/build/outputs/apk/release/app-release.apk

更多构建环境、常见问题、性能优化和真机调试说明见 BUILD_MANUAL.md。

Android APK 构建工作流位于：

.github/workflows/build_android.yaml

当前仓库的 Android 工程位于 Android/src，Gradle wrapper 位于：

Android/src/gradlew

工作流通过 defaults.run.working-directory 固定执行目录：

defaults:
  run:
    working-directory: ./Android/src

因此所有 Gradle 命令都从 Android/src 目录执行。

当前工作流支持手动触发、push 触发和 pull request 触发：

on:
  workflow_dispatch:
  push:
    branches: ["main", "feature/local-api-server"]
    paths:
      - "Android/**"
      - ".github/workflows/build_android.yaml"
  pull_request:
    branches: ["main", "feature/local-api-server"]
    paths:
      - "Android/**"
      - ".github/workflows/build_android.yaml"

适配关系如下：

工作流使用 Ubuntu runner、Temurin JDK 21 和 Gradle 官方缓存：

runs-on: ubuntu-latest

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: "21"

- uses: gradle/actions/setup-gradle@v4

JDK 21 与当前 Android Gradle Plugin / Kotlin 构建链路兼容。Gradle 缓存用于减少后续构建耗时。

工作流构建 Release APK：

- name: Make Gradle wrapper executable
  run: chmod +x ./gradlew

- name: Build release APK
  run: ./gradlew :app:assembleRelease

本地等价命令：

# Enter Android project
cd Android/src

# Build release APK
./gradlew :app:assembleRelease

构建完成后，工作流会执行两步操作：

- name: Upload release APK
  uses: actions/upload-artifact@v4
  with:
    name: google-ai-edge-gallery-local-api-release
    path: Android/src/app/build/outputs/apk/release/app-release.apk

临时下载路径：

1. 打开仓库的 Actions 页面。
2. 选择一次 Build Android APK workflow run。
3. 在页面底部 Artifacts 区域下载 google-ai-edge-gallery-local-api-release。

工作流会自动创建/更新 GitHub Release：

- name: Create Release
  uses: softprops/action-gh-release@v2
  with:
    tag_name: v1.0.15-latest
    name: Gallery Local API - Latest Build
    files: Android/src/app/build/outputs/apk/release/app-release.apk
    prerelease: true

稳定下载地址:

• 直接链接: https://github.com/bugroom/google-ai-edge-gallery-local-api/releases
• Release 标签: v1.0.15-latest（预发布版本）

注意:

• Artifact 保存期为 90 天，Release 中的文件永久保存
• 建议优先从 Releases 页面下载

当前仓库建议保持以下安全配置：

当前默认分支是 feature/local-api-server。如果后续默认分支改为 main，需要同步更新：

• .github/workflows/build_android.yaml 的 branches 列表。
• GitHub 仓库 Settings -> Branches 中的分支保护规则。
• README 中本节的默认分支说明。

修改工作流或 Android 工程结构后，按以下清单检查：

• Android/src/gradlew 是否存在。
• Android/src/settings.gradle.kts 是否存在。
• defaults.run.working-directory 是否仍指向 ./Android/src。
• 构建命令是否仍为 ./gradlew :app:assembleRelease。
• APK 输出路径是否仍为 Android/src/app/build/outputs/apk/release/app-release.apk。
• 触发分支是否包含当前默认分支。
• artifact 上传路径是否匹配实际 APK 输出路径。

• 检查端口是否被占用。
• 检查监听地址是否为 127.0.0.1 或 0.0.0.0。
• 使用 Logcat 搜索 LOCAL_API event=server_start_failed。

• 检查 API Server 页面是否启用了 API Key。
• 检查请求头是否包含 Authorization: Bearer YOUR_API_KEY。
• 使用 Logcat 搜索 LOCAL_API event=auth_failed。

• 先在 App 内下载一个 LLM 模型。
• 仅下载成功且 isLlm = true 的模型会返回。
• 使用 Logcat 搜索 LOCAL_API event=models_list。

• 确认 model 参数等于 /v1/models 返回的 id。
• 确认模型已下载成功。
• 查看 LOCAL_API request_id=<id> 相关日志。
• 重点搜索 model_init_error、inference_start、chat_error、chat_timeout。

• 确认请求体包含 "stream": true。
• 检查客户端是否按 SSE 格式解析 data: 事件。
• 检查客户端是否累积 choices[0].delta.content。
• 检查流结束事件 data: [DONE] 是否到达。

• 多模态输入（图片、音频）暂未开放为 API 参数。
• Token 统计为估算值（按字符数/4）。
• 真机性能取决于设备、模型大小和加速器配置。
• 本地 API 服务随 App 进程运行，App 进程被系统回收后服务会停止。
• 流式响应为逐 token 返回，每个 token 可能包含 1-4 个汉字。

详细的架构设计、接口规范、开发指南和模块说明请查看 .monkeycode/docs/INDEX.md。

文档包含以下内容：

• 系统架构 - 模块关系、请求链路、生命周期
• 接口文档 - HTTP API、请求响应模型、配置字段
• 开发者指南 - 构建、调试、日志排查
• 专有概念 - 本地 API 服务、OpenAI 兼容层、日志诊断
• 模块说明 - API 服务、配置持久化、设置界面

• feat: add local API server support
• feat: connect local API server to LLM inference
• feat: add streaming response support
• feat: add API server sidebar settings
• feat: add API defaults and accelerator settings
• fix: model instance lifecycle management
• fix: streaming response content parsing
• fix: send data: [DONE] at stream end

本项目基于 Google AI Edge Gallery 修改，保留上游 Apache License 2.0 授权。详见 LICENSE。