站点图标 高效码农

Simple Chromium AI使用指南：5分钟掌握Chrome内置AI开发

高效码农

Simple Chromium AI：轻松驾驭 Chrome 内置 AI 的利器

在当今数字化浪潮中，AI 技术正以前所未有的速度融入我们的生活与工作。从智能语音助手到自动化客服，AI 的身影无处不在。对于开发者而言，如何高效便捷地利用 AI 赋能应用，成为提升竞争力的关键。今天，我们要深入探索一个宝藏工具 ——Simple Chromium AI，它如同一把精心打造的钥匙，能轻松开启 Chrome 内置 AI 的大门，为开发之旅带来无限可能。

一、初识 Simple Chromium AI

（一）它是什么？

Simple Chromium AI 是一个轻量级的 TypeScript 包装器，它的诞生旨在简化 Chrome 内置 AI Prompt API 的使用流程。就好比说，Chrome 自带的 AI 是一座功能强大的城堡，而 Simple Chromium AI 就是那条通往城堡的便捷小径，让开发者无需跋山涉水，就能轻松抵达目的地。

（二）为何需要它？

  1. 类型安全的初始化：这就像是给汽车装上了安全带，在启动 AI 之旅前，确保一切都按照正确的方式设置妥当，避免因初始化失误而导致的后续一系列问题。
  2. 自动错误处理：在开发过程中，错误难免会出现。Simple Chromium AI 就像一位贴心的助手，当遇到问题时，能给出清晰明确的错误提示，让你能迅速定位并解决问题，而不是在复杂的错误信息中迷失方向。
  3. 简化 API：它把那些繁琐的代码步骤精简整合，将常见任务浓缩成简洁的一次函数调用。这就如同把一堆散落的零件组装成一个方便使用的工具，让开发者能更专注于核心功能的实现，而不是被复杂的 API 调用所困扰。
  4. 安全 API 变体：提供结果类型，让错误处理更加得心应手，为开发过程增添一份安心保障。

二、快速上手指南

（一）安装

在开始奇妙的开发之旅前，先要安装好这个必备的工具。打开终端，输入以下命令：

npm install simple-chromium-ai

就像为手机安装一个新应用一样，这个简单的步骤就能将 Simple Chromium AI 引入你的项目中。

（二）初始化

import ChromiumAI from 'simple-chromium-ai';

// 初始化一次
const result = await ChromiumAI.initialize("You are a helpful assistant");

这里，我们给 AI 设置了一个系统提示 “You are a helpful assistant”，这就好比给 AI 定了一个基调，让它清楚自己的角色和使命 —— 成为一个乐于助人的助手。

（三）模型下载与实例化

let ai;
if (result.type === 'initialized') {
  // 模型已经可以使用
  ai = result.instance;
} else {
  // 需要通过用户交互来触发下载（例如，按钮点击）
  document.getElementById('download-button').onclick = async () => {
    ai = await result.trigger();
  };
}

Chrome 规定，下载 AI 模型必须要有用户的互动操作来触发。这就好比是设置了一道安全门，防止未经用户同意就自动下载大型文件，占用用户资源。只有当用户主动点击按钮时，才会开始下载模型，并实例化 AI 对象。

（四）简单提示

const response = await ChromiumAI.prompt(ai, "Write a haiku");

这一行代码就像你向 AI 助手抛出一个问题，让它根据你的提示（在这里是 “Write a haiku”，即写一首俳句）来给出回答。它会返回 AI 生成的俳句文本。

（五）使用安全 API 进行错误处理

const safeResponse = await ChromiumAI.Safe.prompt(ai, "Write a haiku");
if (safeResponse.isOk()) {
  console.log(safeResponse.value);
}

使用安全 API 就像是给你的请求加上了一层防护罩。在尝试获取 AI 响应时，先检查是否成功（isOk()），如果是，再获取结果（value），这样就能优雅地处理可能出现的错误情况，避免程序因异常而中断。

三、前置条件大揭秘

在尽情享受 Simple Chromium AI 带来的便捷之前，需要确保满足以下条件：

  1. Chrome 138+：对于扩展程序的运行，需要更新到这个版本或更高版本的 Chrome 浏览器。这就好比不同的手机应用需要对应的操作系统版本支持一样。
  2. Chrome EPP：如果是用于网页端，需要加入 Chrome 的 EPP（Early Preview Program）计划。这可以看作是获取最新、最前沿功能的 “入场券”，让你能提前体验那些尚未全面推广的新特性。
  3. 支持的 Chromium 浏览器：除了官方 Chrome，其他基于 Chromium 内核的浏览器，只要符合要求，也能运行这个工具。这就如同同一种格式的文档，能在不同品牌但同类型的产品中打开。
  4. 启用相关功能：
    • 在 chrome://flags 中启用 “Prompt API for Gemini Nano”。
    • 在 chrome://components 中更新 “Optimization Guide On Device Model”。

这就好比在电脑上安装软件前，需要先开启某些系统服务或更新特定组件，以确保软件能正常运行。

四、核心功能深度剖析

（一）初始化

const result = await ChromiumAI.initialize(
  systemPrompt?: string,
  onDownloadProgress?: (progress: number) => void
);

// 结果是一个带有标记的联合类型
if (result.type === 'initialized') {
  const ai = result.instance;
} else {
  // result.type === 'needs-download'
  const ai = await result.trigger(); // 必须从用户手势（如按钮点击）调用
}

这里，初始化函数接受两个可选参数：系统提示（systemPrompt）和下载进度回调函数（onDownloadProgress）。系统提示能让 AI 明确自己的身份和行为准则。而下载进度回调函数，就像是一个进度条，能实时告知用户模型下载的进度。

当模型已经准备就绪时，结果的类型是 ‘initialized’，直接获取 AI 实例即可使用。反之，当需要下载模型时，结果的类型是 ‘needs-download’，这时需要借助用户交互（如点击按钮）来触发下载。

（二）单次提示

const response = await ChromiumAI.prompt(
  ai,
  "Your prompt",
  timeout?: number
);

这个函数就像是向 AI 发出一个简短的问题或指令。你提供 AI 实例和具体的提示内容，还可以设置超时时间，避免请求因网络或其他原因而长时间无响应。它返回的是 AI 生成的文本结果。

（三）会话管理

  1. 创建可复用会话
const session = await ChromiumAI.createSession(ai);
const response1 = await session.prompt("Hello");
const response2 = await session.prompt("Follow up"); // 保持上下文连贯
session.destroy();

创建会话就像是开启了一段对话。在这个对话中，AI 能记住之前的交流内容，保持上下文的连贯性。就像跟朋友聊天，前一句说到天气，后一句接着说今天的气温，朋友能明白其中的关联。用完会话后，要及时销毁，释放资源。

  1. 自定义会话系统提示
const customSession = await ChromiumAI.createSession(ai, {
  initialPrompts: [{ role: 'system', content: 'You are a pirate' }]
});

在这里，你可以为会话设置独特的系统提示。比如，让 AI 在这个会话中扮演海盗的角色，这样它生成的回复就会符合海盗的风格，增添趣味性。

  1. 使用 withSession 自动清理
const result = await ChromiumAI.withSession(ai, async (session) => {
  return await session.prompt("Hello");
});

这个函数就像是一个自带清理功能的对话容器。你只需要专注于与 AI 的交流内容，它会在交流结束后自动清理会话资源，无需手动销毁，方便又省心。

（四）令牌管理

const usage = await ChromiumAI.checkTokenUsage(ai, "Long text...");
console.log(`Will fit: ${usage.willFit}`);
console.log(`Tokens needed: ${usage.promptTokens}/${usage.maxTokens}`);

令牌就像是交流中的 “额度”。这个函数能检查提示文本所需的令牌数量是否在最大限制内。如果超出了，就像超出了话费额度，可能需要对文本进行精简或优化，以确保 AI 能正常处理。

五、安全 API 的魅力

每个函数都有一个安全变体，它们返回结果类型而不是直接抛出异常。

import { ChromiumAI } from 'simple-chromium-ai';

const result = await ChromiumAI.Safe.initialize("You are helpful");
if (result.isErr()) {
  console.error("Failed:", result.error.message);
  return;
}

const value = result.value;
if (value.type === 'initialized') {
  const ai = value.instance;
  const response = await ChromiumAI.Safe.prompt(ai, "Hello");
} else {
  // 需要用户交互来下载
  button.onclick = async () => {
    const aiResult = await value.trigger();
    if (aiResult.isOk()) {
      const ai = aiResult.value;
      const response = await ChromiumAI.Safe.prompt(ai, "Hello");
    }
  };
}

使用安全 API 就像是给开发过程系上了双保险。在初始化过程中，先检查是否有错误（isErr()），如果有，输出错误信息。当需要用户交互下载模型时，同样先获取结果，再根据结果是否成功（isOk()）来决定后续操作。这种层层把关的方式，能有效避免程序因未处理的异常而崩溃，让开发过程更加稳健。

六、类型安全的保障

TypeScript 的类型系统为 Simple Chromium AI 提供了坚实的保障。

// ❌ 不会编译 —— 需要 AI 实例
await ChromiumAI.prompt("Hello");

// ✅ 正确用法
const result = await ChromiumAI.initialize("You are helpful");
const ai = result.type === 'initialized' 
  ? result.instance 
  : await result.trigger();
await ChromiumAI.prompt(ai, "Hello");

在第一个错误示例中，直接调用 prompt 函数，但未提供 AI 实例，这就违反了类型规则，编译器会及时报错，提醒开发者修正。而在正确用法中，先通过初始化获取结果，根据结果类型判断是否已经初始化成功，获取 AI 实例后再调用 prompt 函数，确保了调用的正确性和安全性。

七、局限性知多少

尽管 Simple Chromium AI 有诸多优点，但它也有自己的局限性，主要体现在以下方面：

  1. 模型参数定制有限：不能对模型参数进行深入细致的定制，只能满足基本需求。
  2. 无法获取流式响应：对于一些需要实时、逐步获取响应的场景，无法提供支持。
  3. 高级会话选项受限：缺乏一些高级的会话配置选项，无法实现复杂会话场景下的精细控制。
  4. 内存/上下文控制不精细：在管理 AI 的记忆和上下文方面，无法做到非常细致入微的控制。

对于这些局限性，如果开发者有更高的要求，可以直接使用原生的 Chromium AI API 来获取更多的灵活性和强大功能。

八、API 参考指南

（一）核心类型

interface ChromiumAIInstance {
  systemPrompt?: string;
  instanceId: string;
}

type InitializeResult = 
  | { type: 'initialized'; instance: ChromiumAIInstance }
  | { type: 'needs-download'; trigger: () => ResultAsync<ChromiumAIInstance, Error> };

interface TokenUsageInfo {
  promptTokens: number;
  maxTokens: number;
  tokensAvailable: number;
  willFit: boolean;
}

这些核心类型定义了 AI 实例的结构、初始化结果的可能情况以及令牌使用信息的细节，为开发过程中的类型检查和代码提示提供了基础。

（二）所有函数及安全变体

函数 描述 返回值
initialize(systemPrompt?, onProgress?) 使用可选的系统提示初始化 AI InitializeResult（带标记的联合类型）
prompt(ai, prompt, timeout?) 带有可选超时的单次提示 string
createSession(ai, options?) 创建可复用会话。选项可以覆盖系统提示 LanguageModel
withSession(ai, callback) 使用临时会话执行操作 T
checkTokenUsage(ai, prompt) 检查提示是否适合上下文 TokenUsageInfo

每个函数都有一个安全变体，它们返回 Result<T, Error> 而不是直接抛出异常，为错误处理提供了更大的便利。

九、精彩示例集锦

（一）基本聊天

const result = await ChromiumAI.initialize("You are a friendly assistant");
const ai = result.type === 'initialized'
  ? result.instance
  : await result.trigger(); // 从用户手势调用
const response = await ChromiumAI.prompt(ai, "Tell me a joke");

在这个简单的聊天示例中，我们让 AI 以友好助手的身份讲一个笑话。通过初始化获取 AI 实例后，直接发送提示，获取笑话文本。

（二）带有进度跟踪

const result = await ChromiumAI.initialize(
  "You are helpful",
  (progress) => console.log(`Downloading: ${progress}%`)
);

if (result.type === 'needs-download') {
  // 从用户交互触发下载
  document.getElementById('download-button').onclick = async () => {
    const ai = await result.trigger();
    // 使用 ai...
  };
}

这里，我们在初始化时设置了下载进度回调函数。当需要下载模型时，点击按钮触发下载，同时在控制台实时显示下载进度，让用户清楚了解下载情况。

（三）处理下载状态

// 显示/隐藏按钮基于模型可用性
const button = document.getElementById('download-button');

try {
  const result = await ChromiumAI.initialize("You are helpful");
  
  if (result.type === 'initialized') {
    // 模型已就绪 —— 隐藏下载按钮
    button.style.display = 'none';
    const ai = result.instance;
    // 使用 AI
    const response = await ChromiumAI.prompt(ai, "Hello!");
  } else {
    // 显示按钮 —— 需要下载
    button.style.display = 'block';
    button.textContent = 'Download AI Model';
    button.onclick = async () => {
      button.disabled = true;
      button.textContent = 'Downloading...';
      try {
        const ai = await result.trigger();
        button.style.display = 'none';
        // 使用 AI
        const response = await ChromiumAI.prompt(ai, "Hello!");
      } catch (error) {
        button.disabled = false;
        button.textContent = 'Retry Download';
        console.error('Download failed:', error);
      }
    };
  }
} catch (error) {
  console.error('Initialization failed:', error);
}

这段代码根据模型是否就绪来动态显示或隐藏下载按钮。在需要下载时，点击按钮开始下载，并在下载过程中更新按钮状态，给用户直观的反馈。

（四）令牌检查

const usage = await ChromiumAI.checkTokenUsage(ai, longText);
if (!usage.willFit) {
  // 使用简短提示
  const response = await ChromiumAI.prompt(ai, "Summarize briefly");
}

在处理长文本时，先检查令牌是否超出限制。如果超出，就改为发送简短的提示，确保 AI 能正常处理，避免因令牌不足而导致请求失败。

（五）带有响应约束的结构化输出

// 定义 JSON 模式用于响应
const schema = {
  type: "object",
  properties: {
    sentiment: {
      type: "string",
      enum: ["positive", "negative", "neutral"]
    },
    confidence: {
      type: "number",
      minimum: 0,
      maximum: 1
    },
    keywords: {
      type: "array",
      items: { type: "string" },
      maxItems: 5
    }
  },
  required: ["sentiment", "confidence", "keywords"]
};

// 创建具有响应约束的会话
const response = await ChromiumAI.prompt(
  ai, 
  "Analyze the sentiment of this text: 'I love this new feature!'",
  undefined, // 无超时
  { responseConstraint: schema }
);

// 响应将是符合模式的有效 JSON
const result = JSON.parse(response);
console.log(result); 
// { sentiment: "positive", confidence: 0.95, keywords: ["love", "new", "feature"] }

这里，我们通过定义 JSON 模式来约束 AI 的响应格式。让 AI 对文本情感进行分析，并以符合模式的 JSON 格式返回结果，包括情感倾向、置信度和关键词等信息，方便后续的数据处理和分析。

（六）可取消的提示

// 创建 AbortController 以取消长时间运行的提示
const controller = new AbortController();

// 设置取消按钮
const cancelButton = document.getElementById('cancel');
cancelButton.onclick = () => controller.abort();

try {
  // 将中止信号传递给提示
  const response = await ChromiumAI.prompt(
    ai, 
    "Write a detailed analysis of quantum computing...",
    undefined, // 无超时
    { signal: controller.signal } // 中止信号
  );
  console.log(response);
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Prompt was cancelled by user');
  } else {
    console.error('Error:', error.message);
  }
}

在处理一些可能需要较长时间的提示时，使用 AbortController 可以让用户提供沉浸式体验。用户随时可以通过点击取消按钮来中止请求，程序能捕获中止事件并做出相应处理，而不是让请求一直无响应地等待下去。

十、常见问题解答（FAQ）

问题一：Simple Chromium AI 支持哪些浏览器？

回答：它主要支持 Chrome 138 及以上版本。此外，支持的 Chromium 浏览器也能运行它，这包括了众多基于 Chromium 内核开发的浏览器产品。但需要注意的是，不同浏览器可能会在功能实现和兼容性上存在细微差异，建议优先使用官方 Chrome 浏览器来确保最佳体验。

问题二：如何处理模型下载失败的情况？

回答：在初始化过程中，如果遇到模型下载失败，首先要检查网络连接是否正常。如果网络没有问题，可以尝试多次重新触发下载。在代码实现上，可以在 catch 块中捕获错误，然后重新调用下载函数，或者提示用户稍后再试。同时，确保在 chrome://flags 中正确启用了相关功能，并更新了必要的组件。

问题三：可以同时创建多个会话吗？

回答：是的，Simple Chromium AI 支持创建多个会话。每个会话都是独立的，有自己的上下文和记忆。你可以同时开启多个会话，让 AI 在不同的角色和话题中切换。但在使用完后，要记得及时销毁会话，释放资源，避免资源占用过多影响性能。

问题四：如何更新 AI 的系统提示？

回答：在初始化时可以设置系统提示，如果想在会话中临时改变系统提示，可以通过在创建会话时设置 initialPrompts 来实现。但对于已经存在的会话，无法直接修改其系统提示。如果需要频繁改变系统提示，可以考虑在每次需要时创建新的会话，并设置相应的系统提示。

问题五：安全 API 和普通 API 在性能上有差异吗？

回答：从功能实现的角度来看，安全 API 主要是在普通 API 的基础上增加了错误处理的逻辑，所以理论上可能会有极微小的性能开销。但在实际使用场景中，这种差异几乎可以忽略不计。而且，安全 API 能有效避免因错误处理不当而导致的程序崩溃等问题，从长期稳定性和可维护性来看，带来的好处远远大于那点微不足道的性能差异。

十一、结语

Simple Chromium AI 就如同一位贴心的向导，带领开发者轻松穿越 Chrome 内置 AI 的复杂丛林。它以简洁的接口、类型安全的保障和强大的功能，为开发过程注入了新的活力。无论是初学者还是经验丰富的开发者，都能借助它快速上手，将 AI 技术融入到各种创意项目中。在数字化的未来，Simple Chromium AI 将成为你开发之路上不可或缺的得力伙伴，助力你打造更加智能、高效的应用，开启无限可能的创新之旅。

退出移动版