# 检索知识与读取证据

在智能体任务的运行环境中检索已授权知识，分页读取命中段落的原文内容，并在确认证据支持回答后提交引用选择。

(sdk-ai-studio-runtime-knowledge-flow)=
## 任务流程

```text
运行任务注入的地址、凭据、工作区与短期授权
                    │
                    ▼
        按关键词检索已绑定知识来源
                    │
                    ▼
   保留 artifact_id / chunk_id / file_id 分页读取证据
                    │
                    ▼
       核实内容依据后提交回答引用选择
```

(sdk-ai-studio-runtime-knowledge-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置，并在任务运行环境中安装匹配的 SDK 包。
2. 保留当前智能体任务注入的服务地址（`MOI_ENDPOINT`）、凭据（`MOI_API_KEY`）、工作区 ID（`MOI_WORKSPACE_ID`）与短期运行授权（`MOI_RUNTIME_AUTHORIZATION`）；任务内检索需同时传入这四项运行时连接参数。
3. 当前任务已绑定可用知识来源，并具备检索、证据读取与引用登记权限。

(sdk-ai-studio-runtime-knowledge-read)=
## 检索并分页读取证据

在任务运行环境中设置检索关键词并执行以下代码。程序提取首个文本命中的产物标识、分段标识、文件标识与语义模型标识，按返回游标循环读取证据内容（单次示例上限为 20 页，防止把尚未读完的长段落误判为完整材料）。

```bash
export KNOWLEDGE_QUERY="retention policy"
```

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
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")
```

::::

::::{tab-item} Go
:sync: go

```go
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")
	}
}
```

::::

:::::

(sdk-ai-studio-runtime-knowledge-cite)=
## 提交回答引用

核实所读证据能够支持回答内容后，接续上例提交引用选择。若回答同时依据多段证据，需在 `sources` 中一并传入全部实际采用的来源。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
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)
```

::::

::::{tab-item} Go
:sync: go

```go
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)
```

::::

:::::

(sdk-ai-studio-runtime-knowledge-limit)=
## 限制和注意事项

- 若引用提交返回未读证据要求，先按要求补齐读取，再重新提交引用选择；检索无足够依据时传空来源列表并在回答中如实说明。
- 需要在解析后的 Markdown 原文中查找或分页浏览上下文时，从检索结果读取 `markdown_file_id`，通过 `knowledge.search_document` 与 `knowledge.read_document`（Go 为 `knowledge.SearchDocument` 与 `knowledge.ReadDocument`）按返回游标继续读取。

(sdk-ai-studio-runtime-knowledge-next)=
## 下一步

- [查看知识库与数据源](../资源中心/管理知识库.md#sdk-ai-studio-knowledge-s1)
