yanmengs-rag-package 0.1.0

package/readme.md

@@ -0,0 +1,233 @@
+# yanmengs-rag-package
+
+集团统一 AI 基建客户端 SDK，封装 RAG 知识库、AI 问答（SSE 流式）、七牛上传、TTS、ASR 等能力，供各业务前端直接调用。
+
+## 安装
+
+```bash
+# 本地链接（开发阶段）
+pnpm link ../yanmengs-ragPackage
+
+# 或发布后通过 npm 安装
+pnpm add yanmengs-rag-package
+```
+
+## 快速开始
+
+```ts
+import { createRagClient } from "yanmengs-rag-package";
+
+const rag = createRagClient({
+  ragServerUrl: "http://your-rag-server:7100", // rag-server 地址
+  appKey: "your_app_key", // 通过 /application/generate_key 获取
+});
+```
+
+> 所有模块均通过 `rag.xxx` 调用，下面逐一说明。
+
+---
+
+## 模块说明
+
+### 1. 七牛上传 `rag.qiniu`
+
+Token 由各应用自行管理，本包只负责上传。
+
+#### 单文件上传
+
+```ts
+rag.qiniu.upload({
+  file: fileObject, // File 或 Blob
+  key: "uploads/2024/doc.pdf", // 七牛存储路径
+  token: "your_qiniu_upload_token", // 方式一：直接传 token
+  // getToken: async () => { ... },   // 方式二：传异步函数获取 token
+  region: "z2", // 可选，默认 z2
+  onProgress: (percent) => {
+    console.log(`上传进度: ${percent.toFixed(1)}%`);
+  },
+  onSuccess: (res) => {
+    console.log("上传成功", res);
+  },
+  onError: (err) => {
+    console.error("上传失败", err.message);
+  },
+});
+```
+
+#### 批量并发上传
+
+```ts
+rag.qiniu.batchUpload({
+  files: [
+    { file: file1, key: "a.pdf" },
+    { file: file2, key: "b.docx" },
+    { file: file3, key: "c.png" },
+  ],
+  token: "your_qiniu_token",
+  maxConcurrency: 3, // 可选，默认 3
+  onItemProgress: (key, percent) => console.log(`${key}: ${percent}%`),
+  onItemSuccess: (key, res) => console.log(`${key} 上传完成`),
+  onItemError: (key, err) => console.error(`${key} 失败`, err),
+  onAllComplete: () => console.log("全部上传完成"),
+});
+```
+
+#### 查看上传队列
+
+```ts
+const list = rag.qiniu.getUploadList();
+// [{ id, name, key, percent, status, error? }, ...]
+```
+
+---
+
+### 2. 知识库 `rag.knowledge`
+
+#### 通过 URL 注入文档
+
+将远程文件自动下载、解析、切片存入向量库。
+
+```ts
+const result = await rag.knowledge.processUrl({
+  userID: "user_001",
+  fileUrl: "https://cdn.example.com/report.pdf",
+  fileID: "biz-file-id", // 可选，用于状态回调
+});
+// result => { message, filename, total_chunks, weaviate_index }
+```
+
+#### 直传文件
+
+```ts
+const result = await rag.knowledge.uploadDocument({
+  userID: "user_001",
+  file: fileObject, // File 对象
+});
+```
+
+#### 删除文档
+
+```ts
+await rag.knowledge.deleteDocument({
+  userID: "user_001",
+  fileID: "xxx", // fileID 和 filename 二选一
+  filename: "可选文件名",
+});
+```
+
+---
+
+### 3. AI 问答 `rag.chat`
+
+#### SSE 流式问答（推荐）
+
+```ts
+rag.chat.askStream({
+  userId: "user_001",
+  query: "项目有哪些技术难点？",
+  topK: 3, // 可选，默认 3
+  onChunk: (chunk) => {
+    // 每收到一段文字就回调，可用于逐字渲染
+    process.stdout.write(chunk);
+  },
+  onDone: (fullAnswer) => {
+    console.log("\n完整回答:", fullAnswer);
+  },
+  onError: (err) => {
+    console.error("问答出错:", err.message);
+  },
+});
+```
+
+#### 非流式问答
+
+```ts
+const result = await rag.chat.ask({
+  userId: "user_001",
+  query: "项目有哪些技术难点？",
+  topK: 3,
+});
+// result => { answer: string, retrieved_context: string[] }
+```
+
+---
+
+### 4. TTS 语音合成 `rag.tts`
+
+流式返回音频数据，可直接喂给 `<audio>` 播放。
+
+```ts
+const response = await rag.tts.stream({ text: "你好，这是一段测试文本" });
+
+// 方式一：直接用 Blob URL 播放
+const blob = await response.blob();
+const audio = new Audio(URL.createObjectURL(blob));
+audio.play();
+
+// 方式二：流式播放（边下载边播放）
+const reader = response.body.getReader();
+// ... 自行处理 ReadableStream
+```
+
+---
+
+### 5. ASR 语音转写 `rag.asr`
+
+```ts
+const result = await rag.asr.transcribe(audioFile);
+// result => { code: 200, data: { text: '识别出的文字内容' } }
+```
+
+---
+
+### 6. 应用管理 `rag.app`
+
+生成 App Key（此接口不需要 app-key 鉴权）。
+
+```ts
+const keyInfo = await rag.app.generateKey("my_app_name");
+// keyInfo => { app_name: 'my_app_name', app_key: 'xxxx', message: 'Key 生成成功' }
+```
+
+---
+
+## 完整类型导出
+
+所有类型均可直接导入使用：
+
+```ts
+import type {
+  RagClientConfig,
+  QiniuUploadOptions,
+  QiniuBatchUploadOptions,
+  UploadItem,
+  ProcessUrlParams,
+  ProcessUrlResult,
+  UploadDocumentParams,
+  UploadDocumentResult,
+  DeleteDocumentParams,
+  AskParams,
+  AskStreamOptions,
+  AskResult,
+  TtsStreamParams,
+  TranscribeResult,
+  GenerateKeyResult,
+} from "yanmengs-rag-package";
+```
+
+## 开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 开发模式（watch）
+pnpm dev
+
+# 构建
+pnpm build
+```
+
+## 支持的文件类型（知识库上传）
+
+PDF、Word、TXT、Excel、PPTX、图片（OCR）