README

PHP SDK for interacting with the WeKnora API.

安装

使用 Composer 安装：

composer require weknora/php-sdk

快速开始

初始化客户端

require_once 'vendor/autoload.php';

use WeKnora\WeKnoraClient;

// 创建客户端实例
$client = new WeKnoraClient(
    'https://api.weknora.com',  // API 基础地址
    'your_api_key_here'         // 您的 API 密钥
);

// 测试连接
if ($client->testConnection()) {
    echo "成功连接到 WeKnora API\n";
}

核心功能模块

1. 租户管理 (Tenant)

// 获取当前租户信息
$tenant = $client->tenant()->getCurrent();

// 获取租户统计
$statistics = $client->tenant()->getStatistics();

// 获取租户成员
$members = $client->tenant()->getMembers();

2. 知识库管理 (Knowledge Base)

// 列出知识库
$knowledgeBases = $client->knowledgeBase()->list();

// 创建知识库
$newKb = $client->knowledgeBase()->create([
    'name' => '我的知识库',
    'description' => '用于存储产品文档'
]);

// 搜索知识库
$searchResults = $client->knowledgeBase()->searchBases('产品文档');

3. 知识管理 (Knowledge)

// 上传文件到知识库
$uploadResult = $client->knowledge()->upload(
    'knowledge-base-id',
    '/path/to/document.pdf',
    ['tags' => ['产品', '文档']]
);

// 搜索知识
$searchResults = $client->knowledge()->search([
    'query' => '如何配置服务器',
    'knowledge_base_id' => 'knowledge-base-id'
]);

// 下载知识文件
$fileContent = $client->knowledge()->download('knowledge-id');

4. 智能体管理 (Agent)

// 列出智能体
$agents = $client->agent()->list();

// 创建智能体
$newAgent = $client->agent()->create([
    'name' => '客服助手',
    'mode' => 'quick-answer',
    'knowledge_base_ids' => ['kb-1', 'kb-2']
]);

// 测试智能体
$testResponse = $client->agent()->test('agent-id', '你好，有什么可以帮助你的？');

5. 会话管理 (Session)

// 创建会话
$session = $client->session()->create([
    'agent_id' => 'agent-id',
    'title' => '客户咨询会话'
]);

// 获取会话消息
$messages = $client->session()->getMessages('session-id');

// 生成会话标题
$title = $client->session()->generateTitle('session-id');

6. 聊天功能 (Chat)

// 基于知识库的聊天
$response = $client->chat()->knowledgeChat('session-id', [
    'message' => '如何配置数据库？',
    'stream' => false
]);

// 基于智能体的聊天
$agentResponse = $client->chat()->agentChat('session-id', [
    'message' => '帮我分析这个数据',
    'tools' => ['calculator', 'web_search']
]);

高级功能

分页和过滤

// 使用分页
$paginatedResults = $client->knowledgeBase()->list(
    page: 2,
    pageSize: 50
);

// 使用过滤
$filteredResults = $client->knowledge()->list(
    page: 1,
    pageSize: 20,
    filters: [
        'tag_id' => 'tag-00000001',
        'file_type' => 'pdf'
    ]
);

批量操作

// 批量删除会话
$success = $client->session()->batchDelete(['session-1', 'session-2']);

// 批量移动知识
$taskInfo = $client->knowledge()->batchMove(
    ['knowledge-1', 'knowledge-2'],
    'target-knowledge-base-id'
);

文件上传

// 上传知识文件
$uploadResult = $client->knowledge()->upload(
    'knowledge-base-id',
    '/path/to/file.pdf',
    [
        'title' => '产品手册',
        'description' => '最新版本产品手册',
        'tags' => ['产品', '文档', '手册']
    ]
);

异步任务处理

// 复制知识库（异步）
$taskInfo = $client->knowledgeBase()->copy(
    'source-kb-id',
    [
        'name' => '副本 - 产品知识库',
        'include_knowledge' => true
    ]
);

// 查询任务进度
$progress = $client->knowledgeBase()->getCopyProgress($taskInfo['task_id']);

错误处理

use WeKnora\Exceptions\ApiException;
use WeKnora\Exceptions\AuthenticationException;

try {
    $result = $client->knowledgeBase()->get('invalid-id');
} catch (AuthenticationException $e) {
    echo "认证失败: " . $e->getMessage() . "\n";
} catch (ApiException $e) {
    echo "API 错误 ({$e->getStatusCode()}): " . $e->getMessage() . "\n";
    echo "错误代码: " . $e->getErrorCode() . "\n";
} catch (\Exception $e) {
    echo "其他错误: " . $e->getMessage() . "\n";
}

配置选项

客户端配置

$client = new WeKnoraClient(
    'https://api.weknora.com',
    'your_api_key_here',
    [
        'timeout' => 60,          // 请求超时时间（秒）
        'connect_timeout' => 10,  // 连接超时时间（秒）
        'headers' => [
            'User-Agent' => 'MyApp/1.0',
            'X-Custom-Header' => 'CustomValue'
        ]
    ]
);

请求追踪

// 设置请求ID用于追踪
$client->setRequestId(uniqid('req_', true));

// 获取当前请求ID
$requestId = $client->getRequestId();

完整示例

创建客服助手工作流

<?php

require_once 'vendor/autoload.php';

use WeKnora\WeKnoraClient;

class CustomerServiceAssistant
{
    private WeKnoraClient $client;
    private string $knowledgeBaseId;
    private string $agentId;
    private string $sessionId;
    
    public function __construct(string $apiKey)
    {
        $this->client = new WeKnoraClient('https://api.weknora.com', $apiKey);
        
        // 创建知识库
        $this->createKnowledgeBase();
        
        // 创建智能体
        $this->createAgent();
        
        // 创建会话
        $this->createSession();
    }
    
    private function createKnowledgeBase(): void
    {
        $kb = $this->client->knowledgeBase()->create([
            'name' => '客服知识库',
            'description' => '包含常见问题解答和产品信息'
        ]);
        
        $this->knowledgeBaseId = $kb['id'];
        
        echo "已创建知识库: {$kb['name']} (ID: {$kb['id']})\n";
    }
    
    private function createAgent(): void
    {
        $agent = $this->client->agent()->create([
            'name' => '客服智能助手',
            'mode' => 'quick-answer',
            'knowledge_base_ids' => [$this->knowledgeBaseId],
            'configuration' => [
                'temperature' => 0.7,
                'max_tokens' => 1000
            ]
        ]);
        
        $this->agentId = $agent['id'];
        
        echo "已创建智能体: {$agent['name']} (ID: {$agent['id']})\n";
    }
    
    private function createSession(): void
    {
        $session = $this->client->session()->create([
            'agent_id' => $this->agentId,
            'title' => '客户咨询'
        ]);
        
        $this->sessionId = $session['id'];
        
        echo "已创建会话: {$session['id']}\n";
    }
    
    public function ask(string $question): string
    {
        try {
            $response = $this->client->chat()->knowledgeChat(
                $this->sessionId,
                ['message' => $question]
            );
            
            return $response['content'] ?? '抱歉，我没有理解您的问题。';
            
        } catch (\Exception $e) {
            return "错误: " . $e->getMessage();
        }
    }
    
    public function uploadDocument(string $filePath, array $metadata = []): bool
    {
        try {
            $result = $this->client->knowledge()->upload(
                $this->knowledgeBaseId,
                $filePath,
                $metadata
            );
            
            echo "已上传文档: {$result['title']}\n";
            return true;
            
        } catch (\Exception $e) {
            echo "上传失败: " . $e->getMessage() . "\n";
            return false;
        }
    }
    
    public function getStatistics(): array
    {
        $kbStats = $this->client->knowledgeBase()->getStatistics($this->knowledgeBaseId);
        $agentStats = $this->client->agent()->getStatistics($this->agentId);
        $sessionStats = $this->client->session()->getStatistics($this->sessionId);
        
        return [
            'knowledge_base' => $kbStats,
            'agent' => $agentStats,
            'session' => $sessionStats
        ];
    }
}

// 使用示例
$apiKey = 'your_api_key_here';
$assistant = new CustomerServiceAssistant($apiKey);

// 上传文档
$assistant->uploadDocument('/path/to/faq.pdf', [
    'title' => '常见问题解答',
    'tags' => ['FAQ', '客服']
]);

// 提问
$answer = $assistant->ask('产品支持电话是多少？');
echo "回答: $answer\n";

// 获取统计信息
$stats = $assistant->getStatistics();
print_r($stats);

支持的 API 模块

基础管理
- tenant() - 租户管理
- organization() - 组织管理
- model() - AI 模型管理
- system() - 系统管理
- tag() - 标签管理
知识库管理
- knowledgeBase() - 知识库管理
- knowledge() - 知识条目管理
- chunk() - 文本分块管理
- faq() - FAQ 管理
- knowledgeSearch() - 知识搜索
智能体管理
- agent() - 智能体管理
- skill() - 技能管理
- mcpService() - MCP 服务管理
对话管理
- session() - 会话管理
- message() - 消息管理
- chat() - 实时聊天
其他功能
- initialization() - 系统初始化
- evaluation() - 评估功能
- webSearch() - 网络搜索

环境要求

PHP 8.0 或更高版本
GuzzleHTTP 7.0 或更高版本
JSON 扩展
cURL 扩展

许可证

MIT License

支持

文档: https://docs.weknora.com
API 参考: https://api.weknora.com/docs
问题反馈: https://github.com/weknora/php-sdk/issues

更新日志

v1.0.0 (初始版本)

完整的 WeKnora API 覆盖
所有核心模块支持
完善的错误处理
异步任务支持
文件上传支持
分页和过滤支持
请求追踪支持

weknora / php-sdk

Maintainers

Package info

Statistics

Security

README

安装

快速开始

初始化客户端

核心功能模块

1. 租户管理 (Tenant)

2. 知识库管理 (Knowledge Base)

3. 知识管理 (Knowledge)

4. 智能体管理 (Agent)

5. 会话管理 (Session)

6. 聊天功能 (Chat)

高级功能

分页和过滤

批量操作

文件上传

异步任务处理

错误处理

配置选项

客户端配置

请求追踪

完整示例

创建客服助手工作流

支持的 API 模块

环境要求

许可证

支持

更新日志

v1.0.0 (初始版本)