Skip to content

Commit 8fcbae2

Browse files
dingyi222666dingyi222666
committed
docs(embedding-model): update embedding model integration documentation
- Simplify code examples by removing unnecessary TypeScript directives - Fix typo in return type from `ChatHubBaseEmbeddings` to `ChatLunaBaseEmbeddings` - Improve structure and readability of embedding implementation guide - Update directory structure display for better visualization - Refactor configuration table to use markdown table format - Clarify steps for implementing embeddings-only platforms - Improve project structure visualization with tree format - Add `@noErrors` directive to code examples for clarity - Refactor configuration section into a markdown table - Update tool calling implementation instructions - Clarify steps for adding embeddings support - Remove redundant section headers for better flow - Add `@noErrors` directive to code examples - Clarify index rebuilding process and requirements - Improve tips formatting with proper markdown syntax - Update reference link description for better context
1 parent e94a979 commit 8fcbae2

File tree

3 files changed

+45
-136
lines changed

3 files changed

+45
-136
lines changed

‎docs/development/connect-to-core-services/embedding-model.md‎

Lines changed: 10 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -14,40 +14,7 @@ ChatLuna 也提供 API，来接入其他的嵌入模型。
1414

1515
将 `src/client.ts` 中的基类从 `PlatformModelClient` 改为 `PlatformModelAndEmbeddingsClient`：
1616

17-
```ts twoslash
18-
// @noImplicitAny: false
19-
import type {} from 'koishi-plugin-chatluna'
20-
import {
21-
PlatformModelAndEmbeddingsClient
22-
} from 'koishi-plugin-chatluna/llm-core/platform/client'
23-
import { ClientConfig } from 'koishi-plugin-chatluna/llm-core/platform/config'
24-
import {
25-
ChatHubBaseEmbeddings,
26-
ChatLunaChatModel,
27-
ChatLunaEmbeddings
28-
} from 'koishi-plugin-chatluna/llm-core/platform/model'
29-
import {
30-
ModelInfo,
31-
ModelType
32-
} from 'koishi-plugin-chatluna/llm-core/platform/types'
33-
import { Context } from 'koishi'
34-
import { ChatLunaPlugin } from 'koishi-plugin-chatluna/services/chat'
35-
import {
36-
ChatLunaError,
37-
ChatLunaErrorCode
38-
} from 'koishi-plugin-chatluna/utils/error'
39-
40-
interface Config {
41-
maxContextRatio: number
42-
frequencyPenalty: number
43-
presencePenalty: number
44-
timeout: number
45-
temperature: number
46-
maxRetries: number
47-
}
48-
49-
class YourPlatformRequester {}
50-
// ---cut---
17+
```ts
5118
export class YourPlatformClient extends PlatformModelAndEmbeddingsClient<ClientConfig> {
5219
platform = 'yourplatform'
5320

@@ -91,7 +58,7 @@ export class YourPlatformClient extends PlatformModelAndEmbeddingsClient<ClientC
9158

9259
protected _createModel(
9360
model: string
94-
): ChatLunaChatModel | ChatHubBaseEmbeddings {
61+
): ChatLunaChatModel | ChatLunaBaseEmbeddings {
9562
const info = this._modelInfos[model]
9663

9764
if (info == null) {
@@ -131,34 +98,7 @@ export class YourPlatformClient extends PlatformModelAndEmbeddingsClient<ClientC
13198

13299
在 `src/requester.ts` 中实现 `EmbeddingsRequester` 接口：
133100

134-
```ts twoslash
135-
// @noImplicitAny: false
136-
import type {} from 'koishi-plugin-chatluna'
137-
import {
138-
ModelRequester,
139-
ModelRequestParams,
140-
EmbeddingsRequester,
141-
EmbeddingsRequestParams
142-
} from 'koishi-plugin-chatluna/llm-core/platform/api'
143-
import {
144-
ClientConfig,
145-
ClientConfigPool
146-
} from 'koishi-plugin-chatluna/llm-core/platform/config'
147-
import * as fetchType from 'undici/types/fetch'
148-
import { ChatGenerationChunk } from '@langchain/core/outputs'
149-
import {
150-
ChatLunaError,
151-
ChatLunaErrorCode
152-
} from 'koishi-plugin-chatluna/utils/error'
153-
import { ChatLunaPlugin } from 'koishi-plugin-chatluna/services/chat'
154-
import { Context, Logger } from 'koishi'
155-
156-
interface Config {
157-
maxRetries: number
158-
}
159-
160-
const logger = {} as Logger
161-
// ---cut---
101+
```ts
162102
export class YourPlatformRequester
163103
extends ModelRequester
164104
implements EmbeddingsRequester {
@@ -254,6 +194,7 @@ export class YourPlatformRequester
254194
#### 输入处理
255195

256196
`embeddings` 方法的 `params.input` 可以是：
197+
257198
- 单个字符串：`"hello world"`
258199
- 字符串数组：`["hello", "world"]`
259200

@@ -262,31 +203,17 @@ export class YourPlatformRequester
262203
#### 返回值
263204

264205
根据输入类型返回不同格式：
206+
265207
- 如果输入是单个字符串，返回 `number[]`（一维向量）
208+
266209
- 如果输入是字符串数组，返回 `number[][]`（向量矩阵）
267210

268211
#### 示例响应处理
269212

270213
以 Gemini 为例：
271214

272-
```ts twoslash
273-
// @noImplicitAny: false
274-
import type {} from 'koishi-plugin-chatluna'
275-
import { EmbeddingsRequestParams, EmbeddingsRequester } from 'koishi-plugin-chatluna/llm-core/platform/api'
276-
import {
277-
ChatLunaError,
278-
ChatLunaErrorCode
279-
} from 'koishi-plugin-chatluna/utils/error'
280-
import { Logger } from 'koishi'
281-
282-
const logger = {} as Logger
283-
284-
class GeminiRequester implements EmbeddingsRequester {
285-
private async _post(url: string, data: any): Promise<Response> {
286-
return {} as Response
287-
}
288-
// ---cut---
289-
async embeddings(
215+
```ts
216+
function embeddings(
290217
params: EmbeddingsRequestParams
291218
): Promise<number[] | number[][]> {
292219
if (typeof params.input === 'string') {
@@ -332,40 +259,13 @@ async embeddings(
332259
throw new ChatLunaError(ChatLunaErrorCode.API_REQUEST_FAILED, error)
333260
}
334261
}
335-
// ---cut-after---
336-
}
337262
```
338263

339264
## 仅支持 Embeddings 的平台
340265

341266
如果你的平台只提供嵌入模型（不支持大语言模型），可以使用 `PlatformEmbeddingsClient`：
342267

343-
```ts twoslash
344-
// @noImplicitAny: false
345-
import type {} from 'koishi-plugin-chatluna'
346-
import { PlatformEmbeddingsClient } from 'koishi-plugin-chatluna/llm-core/platform/client'
347-
import { ClientConfig } from 'koishi-plugin-chatluna/llm-core/platform/config'
348-
import {
349-
ChatHubBaseEmbeddings,
350-
ChatLunaEmbeddings
351-
} from 'koishi-plugin-chatluna/llm-core/platform/model'
352-
import {
353-
ModelInfo,
354-
ModelType
355-
} from 'koishi-plugin-chatluna/llm-core/platform/types'
356-
import { Context } from 'koishi'
357-
import { ChatLunaPlugin } from 'koishi-plugin-chatluna/services/chat'
358-
import {
359-
ChatLunaError,
360-
ChatLunaErrorCode
361-
} from 'koishi-plugin-chatluna/utils/error'
362-
363-
interface Config {
364-
maxRetries: number
365-
}
366-
367-
class YourEmbeddingsRequester {}
368-
// ---cut---
268+
```ts
369269
export class YourEmbeddingsClient extends PlatformEmbeddingsClient<ClientConfig> {
370270
platform = 'yourplatform'
371271

@@ -402,7 +302,7 @@ export class YourEmbeddingsClient extends PlatformEmbeddingsClient<ClientConfig>
402302
})
403303
}
404304

405-
protected _createModel(model: string): ChatHubBaseEmbeddings {
305+
protected _createModel(model: string): ChatLunaBaseEmbeddings {
406306
const info = this._modelInfos[model]
407307

408308
if (info == null) {

‎docs/development/connect-to-core-services/language-model.md‎

Lines changed: 29 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -44,12 +44,16 @@ yarn create chatluna-plugin
4444

4545
模板默认实现了 OpenAI ChatCompletion API 格式，包含以下文件：
4646

47-
- `src/index.ts` - 插件入口和配置
48-
- `src/client.ts` - 平台客户端实现
49-
- `src/requester.ts` - API 请求处理
50-
- `src/types.ts` - 类型定义
51-
- `src/utils.ts` - 工具函数
52-
- `src/locales/` - 国际化文件
47+
```
48+
koishi-plugin-chatluna-adapter-example/
49+
├── src/
50+
│ ├── index.ts # 插件入口和配置
51+
│ ├── client.ts # 平台客户端实现
52+
│ ├── requester.ts # API 请求处理
53+
│ ├── types.ts # 类型定义
54+
│ ├── utils.ts # 工具函数
55+
│ └── locales/ # 国际化文件
56+
```
5357

5458
## 实现核心功能
5559

@@ -61,6 +65,7 @@ yarn create chatluna-plugin
6165

6266
```ts twoslash
6367
// @noImplicitAny: false
68+
// @noErrors
6469
import type {} from 'koishi-plugin-chatluna'
6570
import { ModelInfo, ModelType } from 'koishi-plugin-chatluna/llm-core/platform/types'
6671

@@ -99,6 +104,7 @@ async refreshModels(): Promise<ModelInfo[]> {
99104

100105
```ts twoslash
101106
// @noImplicitAny: false
107+
// @noErrors
102108
import type {} from 'koishi-plugin-chatluna'
103109
import * as fetchType from 'undici/types/fetch'
104110
import { ClientConfig, ClientConfigPool } from 'koishi-plugin-chatluna/llm-core/platform/config'
@@ -143,6 +149,7 @@ private _post(url: string, data: any, params: fetchType.RequestInit = {}) {
143149

144150
```ts twoslash
145151
// @noImplicitAny: false
152+
// @noErrors
146153
import type {} from 'koishi-plugin-chatluna'
147154
import { ModelRequestParams, ModelRequester } from 'koishi-plugin-chatluna/llm-core/platform/api'
148155
import { ChatGenerationChunk } from '@langchain/core/outputs'
@@ -223,6 +230,7 @@ async *completionStreamInternal(
223230

224231
```ts twoslash
225232
// @noImplicitAny: false
233+
// @noErrors
226234
import type {} from 'koishi-plugin-chatluna'
227235
import { ClientConfig } from 'koishi-plugin-chatluna/llm-core/platform/config'
228236

@@ -248,6 +256,7 @@ private _buildHeaders() {
248256

249257
```ts twoslash
250258
// @noImplicitAny: false
259+
// @noErrors
251260
// ---cut-before---
252261
export interface YourPlatformMessage {
253262
role: 'user' | 'assistant' | 'system'
@@ -268,6 +277,7 @@ export interface YourPlatformRequest {
268277

269278
```ts twoslash
270279
// @noImplicitAny: false
280+
// @noErrors
271281
import type {} from 'koishi-plugin-chatluna'
272282
import { ChatLunaPlugin } from 'koishi-plugin-chatluna/services/chat'
273283
import { Schema } from 'koishi'
@@ -303,14 +313,16 @@ export const Config: Schema<Config> = Schema.intersect([
303313

304314
同时记得更新 `src/locales/` 下的国际化文件。
305315

306-
## 配置说明
316+
### 配置说明
307317

308318
模板中的配置已经继承了 `ChatLunaPlugin.Config`，自动提供以下功能：
309319

310-
- 负载均衡：`apiKeys` 支持多个 API Key 配置，ChatLuna 会自动进行负载均衡
311-
- 并发控制：`chatConcurrentMaxSize` 可以控制同一个模型的最大并发请求数
312-
- 重试机制：`maxRetries` 负责控制控制失败重试次数
313-
- 超时设置：`timeout` 可以控制请求 API 的最大超时时间
320+
| 功能 | 配置项 | 说明 |
321+
|------|--------|------|
322+
| 负载均衡 | `apiKeys` | 支持多个 API Key 配置，ChatLuna 会自动进行负载均衡 |
323+
| 并发控制 | `chatConcurrentMaxSize` | 控制同一个模型的最大并发请求数 |
324+
| 重试机制 | `maxRetries` | 控制失败重试次数 |
325+
| 超时设置 | `timeout` | 控制请求 API 的最大超时时间 |
314326

315327
## 测试适配器
316328

@@ -334,19 +346,19 @@ export const Config: Schema<Config> = Schema.intersect([
334346

335347
如果你的平台同时支持 embeddings 模型，可以：
336348

337-
1. 将 `client.ts` 中的基类改为 `PlatformModelAndEmbeddingsClient`
338-
2. 实现 `EmbeddingsRequester` 接口
339-
3. 在 `refreshModels()` 中添加 embeddings 模型
349+
1. 将 `client.ts` 中的基类改为 `PlatformModelAndEmbeddingsClient`。
350+
2. 实现 `EmbeddingsRequester` 接口。
351+
3. 在 `refreshModels()` 中添加 embeddings 模型。
340352

341353
参考 [嵌入模型](./embedding-model.md) 文档了解详情。
342354

343355
### 支持工具调用（Tool Calling）
344356

345357
如果你的平台支持工具调用：
346358

347-
- 在 `requester.ts` 中正确处理 `tools` 参数
348-
- 在 `utils.ts` 中正确格式化工具定义
349-
- 处理工具调用的响应
359+
1. 在 `requester.ts` 中正确处理 `tools` 参数，传递给你的 API 上游。
360+
2. 在 `utils.ts` 中正确格式化工具定义。
361+
3. 处理 API 返回的工具调用响应。
350362

351363
如果不支持，可以在请求中忽略 `tools` 参数。
352364

‎docs/development/connect-to-core-services/vector-database.md‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -220,8 +220,6 @@ export interface MilvusVectorStoreInput
220220

221221
<br>
222222

223-
### 包装类的关键功能
224-
225223
包装类需要实现以下关键方法：
226224

227225
1. `addDocuments`: 添加文档时，为每个文档生成唯一 ID 并存储在 metadata 中
@@ -241,6 +239,7 @@ export interface MilvusVectorStoreInput
241239
```ts twoslash
242240
// @noImplicitAny: false
243241
// @strictNullChecks: false
242+
// @noErrors
244243
import { Context, Schema, Logger } from 'koishi'
245244
import { ChatLunaPlugin } from 'koishi-plugin-chatluna/services/chat'
246245

@@ -400,31 +399,29 @@ function sanitizeMilvusName(name: string) {
400399

401400
<br>
402401

403-
### 注册流程说明
404-
405402
注册向量数据库时，需要完成以下步骤：
406403

407404
1. 获取嵌入模型和唯一标识: 从 `params` 中获取 `embeddings` 和 `key`
408-
2. 创建 DataBaseDocstore: 用于持久化存储文档内容
405+
2. 创建 `DataBaseDocstore`: 用于持久化存储文档内容
409406
3. 初始化向量存储: 创建 LangChain 的向量存储实例
410407
4. 定义重建索引函数: `createCollection` 函数负责在集合损坏或嵌入维度变化时重建索引
411408
5. 初始化检查: 测试向量存储是否正常工作
412409
6. 创建包装实例: 使用自定义的包装类包装向量存储
413410

414-
> [!TIP]
411+
> [!TIP] 提示
415412
> `DataBaseDocstore` 会持久化存储所有文档的内容。当向量数据库集合损坏或嵌入模型维度发生变化时，可以从 `DataBaseDocstore` 恢复所有文档并重新索引。
416413
417414
### 重新索引
418415

419-
你需要手动检查以下的情况：
416+
你需要在实现的代码内手动检查以下的情况：
420417

421418
- 嵌入模型的维度发生变化
422419
- 向量数据库的配置发生变化
423420

424-
当检测到这些情况时，你需要手动掉之前实现的重建索引函数。
421+
当检测到这些情况时，你需要手动调用之前实现的重建索引函数。
425422

426423
注意，重建索引时，你需要从 `DataBaseDocstore` 中读取所有已保存的文档，使用新的嵌入模型重新生成向量并存储。
427424

428425
## 资源参考
429426

430-
请参考 ChatLuna 官方的向量数据库服务插件 [chatluna-vector-store](https://github.com/ChatLunaLab/chatluna/blob/v1-dev/packages/vector-store-service)。
427+
请参考 ChatLuna 官方的向量数据库服务插件 [chatluna-vector-store](https://github.com/ChatLunaLab/chatluna/blob/v1-dev/packages/vector-store-service)，获取更多实现样例。

0 commit comments

Comments
 (0)