知识库注册

字数统计:1.8k 字

阅读时长:6 分钟

💡 提醒

本章教你如何让 AI 学习游戏攻略、角色信息，成为真正的游戏专家。

适合场景：

• 🎮 想让 AI 回答游戏角色、武器、圣遗物的详细问题
• 📖 需要 AI 掌握复杂的游戏机制和攻略
• 🔍 想让 AI 基于插件内容智能检索信息
• 💡 需要动态添加/更新 AI 的知识内容

知识库就像是 AI 的"记忆宫殿"。

你可以把游戏攻略、角色资料、FAQ 等都存进去，当用户问"雷神怎么配装"时，AI 就能从宫殿中找出最相关的知识来回答！

本文档介绍如何在 GsCore AI Core 中注册和管理知识库，为 AI 提供结构化的知识支持。

概述

知识库是 AI 功能的核心组件之一，允许插件开发者注册结构化的知识内容。AI 可以通过检索知识库来回答用户问题。

GsCore 支持两种知识库模式：

• 插件知识库：随插件一起注册，自动同步到向量数据库
• 手动知识库：通过 API 动态添加，适用于运行时内容

插件知识库注册

入口函数

from gsuid_core.ai_core.register import ai_entity

函数签名

def ai_entity(entity: Union[KnowledgeBase, KnowledgePoint]) -> None

参数说明

字段	类型	必填	说明
id	str	是	唯一标识符
plugin	str	是	插件名称
title	str	是	知识点标题
content	str	是	知识点内容（支持 Markdown）
tags	List[str]	是	标签列表
_hash	str	自动	不需传入，自动计算

基础示例

from gsuid_core.ai_core.register import ai_entity
from gsuid_core.ai_core.models import KnowledgeBase

# 在插件初始化时调用
ai_entity(KnowledgeBase(
    id="genshin_character_001",
    plugin="Genshin",
    title="雷电将军 - 角色介绍",
    content="""
    # 雷电将军

    ## 角色信息
    - 元素: 雷
    - 武器: 长枪
    - 命之座: 万世之座

    ## 技能简介
    ### 普通攻击 - 源流
    枪类的普通攻击...

    ### 元素战技 - 奥义 - 梦想真说
    展现梦想的力量...
    """,
    tags=["原神", "雷电将军", "雷神", "角色"],
))

复杂知识库示例

from gsuid_core.ai_core.register import ai_entity
from gsuid_core.ai_core.models import KnowledgeBase

# 注册游戏攻略
ai_entity(KnowledgePoint(
    id="genshin_guide_001",
    plugin="Genshin",
    title="深境螺旋 12 层攻略",
    content="""
    # 深境螺旋 12 层攻略

    ## 怪物配置
    - 12-1 上半: 遗迹守卫 x2
    - 12-1 下半: 深渊法师 x3
    - 12-2 上半: 恒常机关阵列
    - 12-2 下半: 魔偶剑鬼
    - 12-3 上半: 空壳怪组合
    - 12-3 下半: 深海龙蜥

    ## 推荐配队
    ### 上半
    - 队伍1: 雷神 + 班尼特 + 香菱 + 行秋
    - 队伍2: 胡桃 + 钟离 + 夜兰 + 阿贝多

    ### 下半
    - 队伍1: 神里绫华 + 申鹤 + 万叶 + 心海
    - 队伍2: 甘雨 + 温迪 + 莫娜 + 迪奥娜

    ## 注意事项
    1. 注意怪物抗性
    2. 合理分配能量
    3. 利用元素反应
    """,
    tags=["原神", "深境螺旋", "攻略", "12层"],
))

特点

• 在 plugins/ 目录下的插件注册会自动归属到对应插件名
• 启动时自动同步到向量数据库
• 内容变化时会自动更新（基于 _hash 检测）

手动知识库管理

添加手动知识

入口函数

from gsuid_core.ai_core.register import add_manual_knowledge

函数签名

def add_manual_knowledge(entity: ManualKnowledgeBase) -> bool

参数说明

与 ai_entity 相同，但 source 固定为 "manual"

示例

from gsuid_core.ai_core.register import add_manual_knowledge
from gsuid_core.ai_core.models import ManualKnowledgeBase

add_manual_knowledge(ManualKnowledgeBase(
    id="manual_faq_001",
    plugin="custom",
    title="常见问题回答",
    content="""Q: 如何绑定账号？
A: 发送 '绑定 123456' 即可。

Q: 如何查询角色信息？
A: 发送 '角色信息 角色名' 即可。""",
    tags=["FAQ", "绑定"],
))

特点

• 不会在启动时同步
• 适用于通过前端 API 手动添加的内容
• 需要手动管理增删改

手动知识管理 API

函数	签名	说明
add_manual_knowledge	(entity) -> bool	添加知识，已存在返回 False
update_manual_knowledge	(entity_id: str, updates: dict) -> bool	更新知识
delete_manual_knowledge	(entity_id: str) -> bool	删除知识
get_manual_entities	() -> List[ManualKnowledgeBase]	获取所有手动知识
get_manual_entity	(entity_id: str) -> Optional[ManualKnowledgeBase]	获取指定知识

更新手动知识

from gsuid_core.ai_core.register import update_manual_knowledge

# 更新指定 ID 的知识
success = update_manual_knowledge(
    "manual_faq_001",
    {
        "title": "更新后的标题",
        "content": "更新后的内容",
        "tags": ["FAQ", "绑定", "更新"],
    }
)

if success:
    print("更新成功")
else:
    print("更新失败，知识不存在")

删除手动知识

from gsuid_core.ai_core.register import delete_manual_knowledge

# 删除指定 ID 的知识
success = delete_manual_knowledge("manual_faq_001")

if success:
    print("删除成功")
else:
    print("删除失败，知识不存在")

查询手动知识

from gsuid_core.ai_core.register import get_manual_entities, get_manual_entity

# 获取所有手动知识
all_entities = get_manual_entities()
for entity in all_entities:
    print(f"ID: {entity['id']}, Title: {entity['title']}")

# 获取指定知识
entity = get_manual_entity("manual_faq_001")
if entity:
    print(f"内容: {entity['content']}")

知识库内容格式

Markdown 支持

知识库内容支持完整的 Markdown 格式：

content="""
# 一级标题

## 二级标题

### 三级标题

- 列表项1
- 列表项2
  - 子列表项

1. 有序列表1
2. 有序列表2

**粗体文本**

*斜体文本*

`代码片段`

```python
# 代码块
def hello():
    print("Hello")

链接文本

引用文本 """

### 最佳实践

1. **清晰的标题结构**：使用多级标题组织内容
2. **标签策略**：添加相关标签便于检索
3. **内容完整**：提供足够详细的信息
4. **ID 规范**：使用有意义的 ID，如 `plugin_name_content_type_001`

## 知识库检索

AI 会自动使用 `search_knowledge` 工具检索知识库。插件开发者也可以手动调用：

```python
from gsuid_core.ai_core.buildin_tools import search_knowledge
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

async def my_tool(ctx: RunContext[ToolContext]):
    result = await search_knowledge(
        ctx,
        query="雷电将军的技能",
        plugin="Genshin",  # 限定插件
        limit=5,           # 返回5条结果
    )
    return result

完整示例

# my_plugin/knowledge.py

from gsuid_core.ai_core.register import ai_entity, add_manual_knowledge
from gsuid_core.ai_core.models import KnowledgePoint, ManualKnowledgeBase

# 注册插件知识库
def register_plugin_knowledge():
    # 角色信息
    ai_entity(KnowledgePoint(
        id="myplugin_char_001",
        plugin="MyPlugin",
        title="角色A - 详细介绍",
        content="""
        # 角色A

        ## 基础信息
        - 等级: SSR
        - 属性: 火
        - 职业: 战士

        ## 技能
        ### 主动技能
        造成大量火属性伤害...

        ### 被动技能
        攻击时有概率触发...
        """,
        tags=["角色A", "SSR", "火属性", "战士"],
    ))

    # 游戏攻略
    ai_entity(KnowledgePoint(
        id="myplugin_guide_001",
        plugin="MyPlugin",
        title="新手入门攻略",
        content="""
        # 新手入门攻略

        ## 第一天
        1. 完成新手教程
        2. 领取登录奖励
        3. 抽取初始角色

        ## 资源规划
        - 优先升级主力角色
        - 保留高级材料
        - 参与每日活动
        """,
        tags=["新手", "攻略", "入门"],
    ))

# 动态添加 FAQ
def add_faq():
    add_manual_knowledge(ManualKnowledgeBase(
        id="myplugin_faq_001",
        plugin="MyPlugin",
        title="常见问题",
        content="""Q: 如何获得角色A？
A: 角色A可以通过活动卡池抽取获得。

Q: 游戏数据会保留吗？
A: 会，数据与账号绑定。""",
        tags=["FAQ", "角色A", "数据"],
    ))

注意事项

1. ID 唯一性：确保知识库 ID 全局唯一
2. 内容更新：修改内容后 _hash 会自动变化，触发同步
3. 标签选择：选择有意义的标签，便于 AI 检索
4. 性能考虑：大量知识库可能影响启动速度，建议合理组织

下一步

• 工具注册 - 学习如何注册 AI 工具
• Agent创建 - 了解临时 Agent 的用法
• 完整示例 - 查看更多开发示例