@qzsy/kag-sdk

v1.1.5

Published

4 months ago

SDK for accessing KAG services

0High
0Medium
0Low

KAG-SDK

KAG-SDK 是一个用于与知识图谱系统进行交互的 TypeScript/JavaScript SDK。它提供了一系列功能强大的 API，使您能够轻松地管理和操作知识图谱系统。

更新日志

v1.1.5 (2024-01-XX)

重要改进: 完善README文档和示例代码
优化Schema管理相关API的使用说明
新增知识图谱结构解析的详细说明
改进项目文档结构，提供更清晰的使用指导
更新密码加密和安全相关的最佳实践说明

v1.1.4 (2024-01-XX)

新增功能: 添加获取项目图谱结构API
新增 getSchemaGraph 方法，支持获取指定项目的图谱结构
完善图谱相关的TypeScript类型定义
更新示例代码，展示如何获取项目图谱结构

v1.1.3 (2024-01-XX)

更新: 更新服务器地址配置
更新文档中的示例代码和配置说明

v1.1.2 (2024-01-XX)

新增功能: 完善调度任务搜索API
新增通过jobId搜索任务实例列表的接口 searchTaskInstancesByJobId
新增通过instanceId搜索任务详情列表的接口 searchTaskDetailsByInstanceId
完善任务相关的TypeScript类型定义
更新示例代码，展示新增任务搜索接口的使用

v1.1.0 (2024-01-XX)

新增功能: 添加调度实例搜索API支持和SchedulerService服务
新增 SchedulerService 服务类，支持调度实例和任务管理
实现 searchInstance() 方法，支持 /public/v1/scheduler/instance/search API
实现 getInstanceById() 和 searchTask() 方法
修复类型定义兼容性问题，改进BaseResponse类型
更新示例代码，展示scheduler服务的使用

v1.0.3 (2024-01-XX)

重要更新: 登录API现在返回完整的账户信息而不是布尔值
登录成功后可以通过 loginResult.result.token 获取用户token
改进了登录响应的类型定义，提供更好的TypeScript支持
更新了示例代码，展示如何使用返回的token

主要功能

1. 账户管理 (Accounts)

用户登录（返回完整账户信息，包括token）
获取账户信息
更新密码（支持SHA-256加盐加密）
用户退出登录

2. Schema 管理 (Schemas)

创建和更新 Schema
获取图谱差异分析
更新图谱结构
获取图谱结构
获取项目图谱结构（支持实体类型和关系类型的完整定义）
支持实体类型定义和属性配置
支持关系类型定义和索引配置

3. 项目管理 (Projects)

获取项目列表（支持分页和排序）
创建新项目
项目信息查询和管理
支持项目配置和权限管理

4. 权限管理 (Permissions)

获取权限列表
权限验证和管理
用户权限分配

5. 系统配置 (Configs)

获取系统配置
更新配置信息（支持全局配置和LLM配置）
支持版本控制
配置项管理和验证

6. 数据服务 (Datas)

获取枚举值
获取 LLM 模型列表
数据查询和管理
支持数据类型定义

7. 知识构建 (Builder)

获取构建任务列表
查看任务详情
预览分片结果
提交知识构建任务
获取差异分析结果
支持文件上传和处理

8. 推理服务 (Reasoner)

获取推理会话列表
知识图谱查询（KG Query）
文件上传功能
支持多种推理模式
节点和边的查询结果处理

9. 调度服务 (Scheduler)

搜索调度实例
获取调度实例详情
搜索任务
支持分页查询和状态管理
任务实例和详情管理

安装

pnpm install @qzsy/kag-sdk

快速开始

基础配置

import { KAGSDK, KAGError } from '@qzsy/kag-sdk';
import { sha256EncryptWithSalt } from '@qzsy/kag-sdk/utils';

// 创建 SDK 实例
const sdk = new KAGSDK({
  baseURL: 'http://your-server-domain:port',
  timeout: 15000,
  ctoken: 'your_ctoken_here'
});

用户认证

async function authenticate() {
  try {
    // 密码加密（推荐使用SHA-256加盐）
    const plainPassword = 'your_password';
    const salt = 'OPENSPG'; // 默认盐值
    const encryptedPassword = sha256EncryptWithSalt(plainPassword, salt);
    
    // 用户登录
    const loginResult = await sdk.accounts.login({
      account: 'your_account',
      password: encryptedPassword
    });
    
    if (loginResult.success && loginResult.result) {
      const token = loginResult.result.token;
      console.log('登录成功，获取到token:', token);
      return token;
    }
  } catch (error) {
    console.error('登录失败:', error);
  }
}

项目管理

async function manageProjects() {
  // 获取项目列表
  const projectList = await sdk.projects.getProjectList({
    sort: 'desc',
    sortBy: 'time',
    page: 1,
    size: 10
  });
  
  console.log('项目列表:', projectList.result?.results);
  
  // 创建新项目
  const newProject = await sdk.projects.createProject({
    name: '测试项目',
    description: '这是一个测试项目',
    // 其他项目配置...
  });
  
  return projectList.result?.results[0]?.id;
}

Schema图谱管理

async function manageSchema(projectId: number) {
  // 获取项目图谱结构
  const schemaGraph = await sdk.schemas.getSchemaGraph(projectId);
  
  console.log('实体类型列表:', schemaGraph.result.entityTypeDTOList);
  console.log('关系类型列表:', schemaGraph.result.relationTypeDTOList);
  
  // 创建或更新Schema
  const schemaResult = await sdk.schemas.createSchema({
    entityTypes: [
      {
        name: 'Test.Medicine',
        nameZh: '药物',
        description: '药物实体类型',
        // 更多属性定义...
      }
    ],
    relationTypes: [
      {
        name: 'treats',
        nameZh: '治疗',
        startEntity: 'Test.Medicine',
        endEntity: 'Test.Disease'
      }
    ]
  });
  
  return schemaResult;
}

知识构建

async function buildKnowledge(projectId: number) {
  // 获取构建任务列表
  const jobList = await sdk.builder.getJobList({
    projectId,
    start: 1,
    limit: 10
  });
  
  if (jobList.result.data.length > 0) {
    const jobId = jobList.result.data[0].id;
    
    // 获取任务详情
    const jobDetail = await sdk.builder.getJob({ id: jobId });
    
    // 预览分片结果
    const previewResult = await sdk.builder.previewSplit(jobDetail.result);
    
    console.log('分片预览:', previewResult);
  }
}

知识图谱查询

async function queryKnowledgeGraph(projectId: number, jobId: number) {
  // 执行KG查询
  const kgQuery = await sdk.reasoner.getKGQuery({
    id: jobId,
    jobId
  });
  
  console.log('查询结果节点:', kgQuery.result.resultNodes);
  console.log('查询结果边:', kgQuery.result.resultEdges);
  
  // 获取差异分析
  const diffResult = await sdk.builder.getDiffResult({
    job: jobDetail.result,
    subGraph: {
      resultNodes: kgQuery.result.resultNodes,
      resultEdges: kgQuery.result.resultEdges
    }
  });
  
  return diffResult;
}

配置管理

async function manageConfigs() {
  // 获取系统配置
  const config = await sdk.configs.getConfig({
    configId: 'KAG_CONFIG',
    version: 1
  });
  
  console.log('系统配置:', config.result);
  
  // 更新配置
  const updateResult = await sdk.configs.updateConfig({
    configData: {
      // 配置数据...
    }
  });
  
  return updateResult;
}

理解知识图谱结构

实体类型 (EntityType)

实体类型定义了知识图谱中节点的结构：

interface EntityType {
  id: number;                    // 实体类型唯一ID
  name: string;                  // 英文名称（如：'Test.Medicine'）
  nameZh: string;                // 中文名称（如：'药物'）
  description: string;           // 描述信息
  inheritedPropertyList: Property[]; // 继承的属性列表
  propertyList: Property[];      // 自定义属性列表
  relations: Relation[];         // 关系定义
  parentId: number;              // 父类ID
  parentName: string;            // 父类名称（如：'Thing'）
  belongToProject: number;       // 所属项目ID
  entityCategory: string;        // 实体类别
}

关系类型 (RelationType)

关系类型定义了实体之间的连接：

interface RelationType {
  name: string;                  // 英文名称（如：'treats'）
  nameZh: string;                // 中文名称（如：'治疗'）
  startEntity: EntityType;       // 起始实体类型
  endEntity: EntityType;         // 终止实体类型
  propertyList: Property[];      // 关系属性列表
  relationCategory: string;      // 关系类别
}

最佳实践

1. 安全性

始终使用加密密码进行登录
定期更新访问令牌
妥善保管ctoken和敏感信息

2. 错误处理

try {
  const result = await sdk.someMethod();
  // 处理成功结果
} catch (error) {
  if (error instanceof KAGError) {
    console.error('KAG错误:', error.message);
  } else {
    console.error('未知错误:', error);
  }
}

3. 性能优化

合理设置超时时间
使用分页查询大量数据
缓存频繁访问的配置信息

API参考

完整的API文档请参考TypeScript类型定义文件，所有方法都有详细的类型注解和注释说明。

特性

✅ 完整的 TypeScript 支持
✅ 简单易用的 API 设计
✅ 完善的错误处理机制
✅ 支持自定义配置
✅ 支持异步操作
✅ 内置密码加密工具
✅ 完整的知识图谱管理功能

注意事项

使用前需要先进行初始化和登录
部分功能可能需要特定的权限
建议参考示例代码进行开发
密码需要使用SHA-256加盐加密
确保网络连接稳定，合理设置超时时间

示例代码

完整的使用示例请查看 example/sdk-usage.ts 文件，其中包含了所有主要功能的使用方法。

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。