在 Vue 3 项目中接入大模型能力时，最初通常只需要完成一次接口调用和一次页面展示。但随着功能逐渐进入真实业务场景，请求生命周期、流式响应、多 Provider 适配、错误处理、停止生成、线程恢复、密钥安全等问题都会变成需要统一处理的工程问题。

vue-ai-hooks 是一个面向 Vue 3 的 AI Composable 库，目标是把这些重复的请求状态和生命周期逻辑沉淀成可复用 API。它不提供固定 UI，也不替代后端 Agent 框架，而是专注于前端侧的 AI 请求管理。

项目地址：

https://github.com/hexinmiao96/vue-ai-hooks

安装方式：

pnpm add vue-ai-hooks

项目定位

vue-ai-hooks 的核心定位是：为 Vue 3 应用提供一组用于构建 AI 功能的组合式函数。

它主要解决以下问题：

• 统一管理聊天、补全、结构化输出等 AI 请求状态。
• 封装 SSE / Stream 场景下的增量响应处理。
• 提供中止请求、错误状态、加载状态、生命周期回调等通用能力。
• 支持 OpenAI、DeepSeek、Moonshot、智谱、Ollama、vLLM 等常见模型服务或 OpenAI-compatible 接口。
• 支持生产环境通过后端代理调用上游模型，避免浏览器暴露 API Key。
• 保持 UI 无关，便于集成到已有 Vue 项目和组件体系中。

这类能力如果分散在不同页面中手写，短期可以工作，长期会造成状态管理和异常处理不一致。将其抽象为 composable，更符合 Vue 3 项目的组织方式。

基础聊天示例

下面是一个最小可用的流式聊天示例：

<script setup lang="ts">
import { useChat, openai } from 'vue-ai-hooks'

const { messages, input, handleSubmit, isLoading, stop, error } = useChat({
  provider: openai({
    apiKey: import.meta.env.VITE_OPENAI_KEY
  })
})
</script>

<template>
  <div>
    <div v-for="message in messages" :key="message.id">
      <strong>{{ message.role }}：</strong>
      <span>{{ message.content }}</span>
    </div>

    <form @submit="handleSubmit">
      <textarea v-model="input" />
      <button :disabled="isLoading || !input.trim()">发送</button>
      <button type="button" :disabled="!isLoading" @click="stop">停止</button>
    </form>

    <p v-if="error">{{ error.message }}</p>
  </div>
</template>

在这个例子中，页面组件只负责渲染消息和处理用户交互。请求发起、流式内容合并、停止生成、错误暴露等逻辑由 useChat 统一处理。

生产环境接入建议

示例代码中直接使用 VITE_OPENAI_KEY 更适合本地调试或受限场景。需要注意的是，前端环境变量会进入浏览器产物，不能用于保存生产环境的真实模型密钥。

正式项目更推荐采用后端代理：

Vue 页面
  -> vue-ai-hooks
  -> 业务后端 /api/chat
  -> OpenAI / DeepSeek / 智谱 / Ollama / vLLM / 其他模型服务

前端侧只访问业务后端接口：

import { useChat, proxy } from 'vue-ai-hooks'

const { messages, input, handleSubmit, isLoading } = useChat({
  provider: proxy({
    api: '/api/chat'
  }),
  metadata: {
    source: 'customer-service-panel'
  }
})

这种方式可以将 API Key、鉴权、限流、日志、模型路由、敏感内容处理等逻辑放到服务端，前端只负责交互状态和展示逻辑。

多 Provider 支持

大模型服务的选型经常会变化。一个项目在不同阶段可能会使用 OpenAI-compatible 接口、本地模型、第三方模型平台或公司内部模型网关。

vue-ai-hooks 提供了常见 Provider preset，包括：

• OpenAI
• Gemini
• OpenRouter
• Anthropic
• DeepSeek
• Moonshot
• 智谱
• Ollama
• vLLM
• OpenAI-compatible API

例如接入 DeepSeek：

import { useChat, deepseek } from 'vue-ai-hooks'

const chat = useChat({
  provider: deepseek({
    apiKey: import.meta.env.VITE_DEEPSEEK_KEY
  })
})

如果业务侧已经有统一模型网关，则可以使用 proxy() 接入自有接口，从而降低前端对具体模型厂商的依赖。

主要能力

vue-ai-hooks 不只覆盖聊天场景，也包含多种 AI 应用中常见的任务类型。

Composable	用途
useChat	多轮聊天、流式消息
useCompletion	文本补全
useEmbedding	向量生成
useGeneration	通用生成任务
useImage	图片生成和编辑
useVideo	视频生成
useSpeech	语音生成
useTranscription	语音转写
useRerank	文档重排
useObject	JSON 结构化输出
useChatThreads	聊天线程管理
useAgentContext	注入应用上下文
useAgentCapabilities	读取后端声明的 Agent 能力
useAgentRun	管理 Agent event stream 状态
usePromptSuggestions	输入建议

其中 useObject 适合处理结构化输出。例如，将自然语言整理成固定 JSON：

import { useObject, openai } from 'vue-ai-hooks'

const { object, partialObject, submit, isLoading } = useObject<{
  title: string
  priority: 'low' | 'high'
}>({
  provider: openai({ apiKey: import.meta.env.VITE_OPENAI_KEY }),
  schema: {
    type: 'object',
    properties: {
      title: { type: 'string' },
      priority: { type: 'string', enum: ['low', 'high'] }
    },
    required: ['title', 'priority']
  }
})

await submit('把这段需求整理成任务标题和优先级')

这类能力可以用于工单分类、表单预填、审批意见提取、标签生成、需求摘要等业务场景。

为什么不绑定 UI

vue-ai-hooks 没有提供固定的聊天窗口、消息气泡或 Copilot 面板，这是一个有意保留的边界。

在实际项目中，前端应用通常已经使用了固定的组件库和设计规范，例如 Element Plus、Ant Design Vue、Naive UI 或公司内部组件库。如果 AI SDK 绑定完整 UI，集成到既有系统时反而容易产生样式和交互割裂。

因此，vue-ai-hooks 只提供状态和行为：

• messages
• input
• isLoading
• error
• handleSubmit
• stop
• sendMessage

页面层仍由业务项目自行实现。这样既能复用请求逻辑，也不会影响现有 UI 体系。

与手写 fetch 的区别

对于简单 demo，直接使用 fetch 调用模型接口完全可行。但当项目中出现多个 AI 页面或多个模型能力时，重复逻辑会逐渐增加。

一个较完整的聊天功能通常需要处理：

• 消息列表维护
• 输入状态
• Stream 解析
• 请求中断
• 错误处理
• 请求重试
• 生命周期回调
• 请求 metadata
• 线程恢复
• 工具调用结果
• 调试 trace

这些逻辑如果分散在不同页面中，后续维护成本会持续增加。vue-ai-hooks 的价值在于将这部分通用逻辑抽成稳定 API，使不同页面保持一致的请求行为和状态结构。

React 子入口

虽然该库主要面向 Vue 3，但也提供了可选 React 子入口：

import { useChat, useCompletion, useObject } from 'vue-ai-hooks/react'

这个入口主要用于迁移或混合技术栈场景。React 页面可以复用同一套 Provider 和请求类型，接入聊天、补全、结构化输出、图片、视频、Agent run 等能力。

如果项目只使用 Vue，可以忽略该入口。

工程化情况

从仓库结构看，vue-ai-hooks 不只是示例代码集合，也包含相对完整的库级工程配置：

• TypeScript strict
• ESM / CJS 构建
• Vitest 测试
• VitePress 文档
• 示例项目
• secret 检查
• source hygiene 检查
• package / install 检查
• docs / examples build
• pnpm production:readiness 生产可用性检查

示例目录覆盖 chat、completion、embedding、image、video、speech、transcription、rerank、object、threaded chat、agent run、proxy server 等场景。阅读示例代码可以更快理解各 composable 的实际使用方式。

适用场景

vue-ai-hooks 比较适合以下几类项目：

1. Vue 3 中后台系统，需要在已有页面中加入 AI 助手或智能输入能力。
2. 需要快速验证大模型能力的原型项目。
3. 需要在 OpenAI-compatible、本地模型、第三方平台和内部模型网关之间切换的项目。
4. 已经有后端代理层，希望前端专注于状态管理和交互展示的生产项目。
5. 需要结构化输出、线程管理、Agent event stream 等能力，但不希望引入完整 UI 框架的项目。

总结

vue-ai-hooks 的目标不是做一个完整 AI 平台，也不是替代 LangChain、LangGraph 等后端编排工具。它更适合作为 Vue 项目中的 AI 请求工具层，用于统一管理聊天、补全、结构化输出、流式响应、Provider、线程和 Agent event 等前端状态。

如果项目已经使用 Vue 3，并且需要接入大模型能力，可以通过这个库减少重复的请求生命周期代码，同时保留现有 UI 和后端架构。

项目地址：

https://github.com/hexinmiao96/vue-ai-hooks