零服务器也能玩转结构化数据：WebLLM JSON Schema全攻略-优快云博客

零服务器也能玩转结构化数据：WebLLM JSON Schema全攻略

【免费下载链接】web-llm 将大型语言模型和聊天功能引入网络浏览器。所有内容都在浏览器内部运行，无需服务器支持。项目地址: https://gitcode.com/GitHub_Trending/we/web-llm

你是否还在为浏览器端AI输出格式混乱而头疼？想让本地大模型严格按照指定结构返回数据却苦于没有简单方案？本文将带你掌握WebLLM JSON Schema（结构化约束输出）的高级用法，通过三个实战案例，让浏览器内运行的AI模型乖乖"听话"输出规范JSON。读完你将获得：

零服务器环境下实现结构化数据生成的完整流程
三种Schema定义技巧（基础类型/嵌套结构/枚举约束）
生产级函数调用与AI工具集成方案
避坑指南与性能优化策略

什么是WebLLM JSON Schema？

WebLLM作为能在浏览器内运行大型语言模型的开源项目，其JSON Schema功能允许开发者通过JSON格式定义输出模板，强制AI模型生成符合规范的结构化数据。这种约束能力在表单生成、数据分析、API调用等场景中至关重要。

官方示例项目提供了完整的实现代码，你可以在examples/json-schema/src/json_schema.ts中查看全部源码，或直接运行json_schema.html体验效果。

快速上手：基础类型约束

最常见的场景是要求AI返回包含特定基础类型字段的JSON对象。WebLLM支持两种Schema定义方式：直接JSON字符串和TypeBox库生成。

直接JSON定义

const schema1 = `{
  "properties": {
    "size": {"title": "Size", "type": "integer"}, 
    "is_accepted": {"title": "Is Accepted", "type": "boolean"}, 
    "num": {"title": "Num", "type": "number"}
  },
  "required": ["size", "is_accepted", "num"], 
  "title": "Schema", "type": "object"
}`;

TypeBox库生成（推荐）

使用TypeBox可以获得类型安全和自动验证能力：

import { Type, Static } from "@sinclair/typebox";

const T = Type.Object({
  size: Type.Integer(),
  is_accepted: Type.Boolean(),
  num: Type.Number(),
});
type T = Static<typeof T>; // 类型安全保障
const schema2 = JSON.stringify(T);

请求配置

将Schema传入WebLLM的聊天请求参数：

const request: webllm.ChatCompletionRequest = {
  stream: false,
  messages: [{
    role: "user",
    content: "Generate a json containing three fields: an integer field named size, a boolean field named is_accepted, and a float field named num."
  }],
  max_tokens: 128,
  response_format: {
    type: "json_object",
    schema: schema2
  } as webllm.ResponseFormat
};

高级应用：嵌套结构与枚举约束

对于更复杂的数据结构，如包含嵌套对象和枚举值的场景，JSON Schema能提供精确控制。以魔法世界角色信息提取为例：

复杂Schema定义

const T = Type.Object({
  name: Type.String(),
  house: Type.Enum({
    Gryffindor: "Gryffindor",
    Hufflepuff: "Hufflepuff",
    Ravenclaw: "Ravenclaw",
    Slytherin: "Slytherin",
  }),
  blood_status: Type.Enum({
    "Pure-blood": "Pure-blood",
    "Half-blood": "Half-blood",
    "Muggle-born": "Muggle-born",
  }),
  occupation: Type.Enum({
    Student: "Student",
    Professor: "Professor",
    "Ministry of Magic": "Ministry of Magic",
    Other: "Other",
  }),
  wand: Type.Object({
    wood: Type.String(),
    core: Type.String(),
    length: Type.Number(),
  }),
  alive: Type.Boolean(),
  patronus: Type.String(),
});

生成效果

AI将严格按照定义返回数据：

{
  "name": "赫敏·格兰杰",
  "house": "Gryffindor",
  "blood_status": "Muggle-born",
  "occupation": "Student",
  "wand": {
    "wood": "Vine",
    "core": "Dragon heartstring",
    "length": 10.75
  },
  "alive": true,
  "patronus": "Otter"
}

完整实现见examples/json-schema/src/json_schema.ts。

函数调用：AI工具调用的标准化方案

WebLLM JSON Schema可与函数调用功能结合，实现AI工具调用的标准化输出。以下是天气查询工具调用示例：

工具定义

const tools: Array<webllm.ChatCompletionTool> = [{
  type: "function",
  function: {
    name: "get_current_weather",
    description: "Get the current weather in a given location",
    parameters: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "The city and state, e.g. San Francisco, CA"
        },
        unit: { type: "string", enum: ["celsius", "fahrenheit"] }
      },
      required: ["location"]
    }
  }
}];

函数调用Schema

const T = Type.Object({
  tool_calls: Type.Array(
    Type.Object({
      arguments: Type.Any(),
      name: Type.String(),
    })
  )
});

系统提示设计

const systemPrompt = `You are a function calling AI model. You are provided with function signatures within <tools></tools> XML tags. You may call one or more functions to assist with the user query. Don't make assumptions about what values to plug into functions. Here are the available tools: <tools> ${JSON.stringify(tools)} </tools>. Return a valid json object in the following schema: ${JSON.stringify(schema)}.`;

完整代码见examples/json-schema/src/json_schema.ts。

性能优化与最佳实践

模型选择

推荐使用对JSON生成优化的模型：

Llama-3.2-3B-Instruct-q4f16_1-MLC
Qwen2.5-1.5B-Instruct-q4f16_1-MLC
Phi-3.5-mini-instruct-q4f16_1-MLC

缓存策略

启用IndexedDB缓存加速模型加载：

const engine = await CreateMLCEngine("Llama-3.2-3B-Instruct-q4f16_1-MLC", {
  appConfig: {
    useIndexedDB: true
  },
  initProgressCallback: initProgressCallback
});

详细配置见docs/user/advanced_usage.rst。

错误处理

实现初始化进度回调监控加载状态：

const initProgressCallback = (report: webllm.InitProgressReport) => {
  setLabel("init-label", report.text);
};

总结与扩展

WebLLM JSON Schema为浏览器端AI提供了强大的结构化输出能力，从简单数据提取到复杂工具调用均能胜任。除JSON Schema外，WebLLM还支持EBNF语法定义，满足更复杂的格式需求，详见examples/json-schema/src/json_schema.ts的EBNF示例。

通过本文介绍的方法，你可以在无服务器环境下实现AI输出的精准控制，为Web应用添加智能数据处理能力。更多高级用法请参考官方文档docs/user/advanced_usage.rst。

现在就克隆项目体验：git clone https://gitcode.com/GitHub_Trending/we/web-llm，开启浏览器端AI的结构化数据之旅！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考