检索知识与读取证据¶
在智能体任务的运行环境中检索已授权知识,分页读取命中段落的原文内容,并在确认证据支持回答后提交引用选择。
任务流程¶
运行任务注入的地址、凭据、工作区与短期授权
│
▼
按关键词检索已绑定知识来源
│
▼
保留 artifact_id / chunk_id / file_id 分页读取证据
│
▼
核实内容依据后提交回答引用选择
准备¶
已完成 使用 SDK 中的服务地址、个人访问令牌与工作区配置,并在任务运行环境中安装匹配的 SDK 包。
保留当前智能体任务注入的服务地址(
MOI_ENDPOINT)、凭据(MOI_API_KEY)、工作区 ID(MOI_WORKSPACE_ID)与短期运行授权(MOI_RUNTIME_AUTHORIZATION);任务内检索需同时传入这四项运行时连接参数。当前任务已绑定可用知识来源,并具备检索、证据读取与引用登记权限。
检索并分页读取证据¶
在任务运行环境中设置检索关键词并执行以下代码。程序提取首个文本命中的产物标识、分段标识、文件标识与语义模型标识,按返回游标循环读取证据内容(单次示例上限为 20 页,防止把尚未读完的长段落误判为完整材料)。
export KNOWLEDGE_QUERY="retention policy"
import os
import uuid
from google.protobuf.json_format import MessageToDict
from google.protobuf.struct_pb2 import Struct, Value
import moi_product_sdk as sdk
client = sdk.Client(
os.environ["MOI_ENDPOINT"],
sdk.with_api_key(os.environ["MOI_API_KEY"]),
sdk.with_runtime_authorization(os.environ["MOI_RUNTIME_AUTHORIZATION"]),
)
knowledge = client.workspace(os.environ["MOI_WORKSPACE_ID"]).knowledge()
def checked(result):
if result.failed:
raise RuntimeError(MessageToDict(result.output))
return MessageToDict(result.output)
search = knowledge.search(
sdk.KnowledgeSearchRequest(
request_id="search-" + uuid.uuid4().hex,
keywords=[os.environ["KNOWLEDGE_QUERY"]],
max_hits=3,
before=2,
after=1,
)
)
checked(search)
choices = []
for artifact in search.artifacts:
saved = MessageToDict(artifact)
for chunk in saved.get("data", {}).get("chunks", []):
if chunk.get("chunk_id") and saved.get("artifact_id"):
choices.append((saved["artifact_id"], chunk))
if not choices:
raise SystemExit("No text evidence returned; inspect the search result.")
artifact_id, chunk = choices[0]
selection = {"type": "rag_chunk", "artifact_id": artifact_id}
for key in ("chunk_id", "file_id", "semantic_model_id"):
if key in chunk:
selection[key] = chunk[key]
print("Selected evidence:", selection)
cursor = 0
for _ in range(20):
request = sdk.KnowledgeReadEvidenceRequest(
request_id="read-" + uuid.uuid4().hex,
artifact_id=artifact_id,
chunk_id=chunk["chunk_id"],
file_id=chunk["file_id"],
cursor=Value(number_value=cursor),
limit_chars=4000,
)
if "semantic_model_id" in chunk:
request.semantic_model_id = int(chunk["semantic_model_id"])
page = checked(knowledge.read_evidence(request))
print(page.get("content", ""))
if not page.get("has_more", False):
break
next_cursor = page.get("next_cursor")
if not isinstance(next_cursor, (int, float)) or next_cursor <= cursor:
raise RuntimeError("Invalid evidence continuation cursor")
cursor = next_cursor
else:
raise RuntimeError("Read budget reached; finish reading before citing")
package main
import (
"context"
"fmt"
"os"
"time"
sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
"google.golang.org/protobuf/types/known/structpb"
)
func checked(result *sdk.KnowledgeRuntimeResult, err error) map[string]any {
if err != nil {
panic(err)
}
if result.GetFailed() {
panic(fmt.Sprint(result.GetOutput().AsMap()))
}
return result.GetOutput().AsMap()
}
func requestID(prefix string) string {
return fmt.Sprintf("%s-%d", prefix, time.Now().UnixNano())
}
func main() {
ctx := context.Background()
client, err := sdk.New(
os.Getenv("MOI_ENDPOINT"),
sdk.WithAPIKey(os.Getenv("MOI_API_KEY")),
sdk.WithRuntimeAuthorization(os.Getenv("MOI_RUNTIME_AUTHORIZATION")),
)
if err != nil {
panic(err)
}
defer client.Close()
workspace, err := client.Workspace(os.Getenv("MOI_WORKSPACE_ID"))
if err != nil {
panic(err)
}
knowledge := workspace.Knowledge()
search, err := knowledge.Search(ctx, &sdk.KnowledgeSearchRequest{
RequestId: requestID("search"),
Keywords: []string{os.Getenv("KNOWLEDGE_QUERY")},
MaxHits: 3,
Before: 2,
After: 1,
})
checked(search, err)
var artifactID string
var chunk map[string]any
for _, artifact := range search.GetArtifacts() {
saved := artifact.AsMap()
data, _ := saved["data"].(map[string]any)
chunks, _ := data["chunks"].([]any)
for _, value := range chunks {
candidate, ok := value.(map[string]any)
id, _ := saved["artifact_id"].(string)
if ok && candidate["chunk_id"] != nil && id != "" {
artifactID, chunk = id, candidate
break
}
}
if chunk != nil {
break
}
}
if chunk == nil {
fmt.Println("No text evidence returned; inspect the search result.")
return
}
selection := map[string]any{"type": "rag_chunk", "artifact_id": artifactID}
for _, key := range []string{"chunk_id", "file_id", "semantic_model_id"} {
if value, ok := chunk[key]; ok {
selection[key] = value
}
}
fmt.Println("Selected evidence:", selection)
cursor := float64(0)
complete := false
for pageIndex := 0; pageIndex < 20; pageIndex++ {
request := &sdk.KnowledgeReadEvidenceRequest{
RequestId: requestID("read"),
ArtifactId: artifactID,
ChunkId: chunk["chunk_id"].(string),
FileId: chunk["file_id"].(string),
Cursor: structpb.NewNumberValue(cursor),
LimitChars: 4000,
}
if value, ok := chunk["semantic_model_id"].(float64); ok {
modelID := int64(value)
request.SemanticModelId = &modelID
}
page := checked(knowledge.ReadEvidence(ctx, request))
fmt.Println(page["content"])
if page["has_more"] != true {
complete = true
break
}
next, ok := page["next_cursor"].(float64)
if !ok || next <= cursor {
panic("Invalid evidence continuation cursor")
}
cursor = next
}
if !complete {
panic("Read budget reached; finish reading before citing")
}
}
提交回答引用¶
核实所读证据能够支持回答内容后,接续上例提交引用选择。若回答同时依据多段证据,需在 sources 中一并传入全部实际采用的来源。
source = Struct()
source.update(selection)
citation = knowledge.cite(
sdk.KnowledgeCiteRequest(
request_id="cite-" + uuid.uuid4().hex,
sources=[source],
complete_read_requirements=True,
)
)
confirmation = checked(citation)
if confirmation.get("accepted") is not True:
raise RuntimeError(confirmation)
print("Citation accepted:", confirmation)
source, err := structpb.NewStruct(selection)
if err != nil {
panic(err)
}
confirmation := checked(knowledge.Cite(ctx, &sdk.KnowledgeCiteRequest{
RequestId: requestID("cite"),
Sources: []*structpb.Struct{source},
CompleteReadRequirements: true,
}))
if confirmation["accepted"] != true {
panic(fmt.Sprint(confirmation))
}
fmt.Println("Citation accepted:", confirmation)
限制和注意事项¶
若引用提交返回未读证据要求,先按要求补齐读取,再重新提交引用选择;检索无足够依据时传空来源列表并在回答中如实说明。
需要在解析后的 Markdown 原文中查找或分页浏览上下文时,从检索结果读取
markdown_file_id,通过knowledge.search_document与knowledge.read_document(Go 为knowledge.SearchDocument与knowledge.ReadDocument)按返回游标继续读取。
下一步¶
最后更新于