6f8b825f5f
The `weknora` command-line client for the WeKnora RAG server. Full command surface: kb / doc / chunk / session / message / agent / model / search / chat / auth / profile / link / api / mcp / skills / config / doctor / schema / exit-codes. Agent-first wire contract: JSON envelope by default, typed error codes mapped to stable exit codes, error.retry_argv / retryable / partial-failure status, global --dry-run preview, the exit-10 confirmation protocol for writes, and control/ANSI/Bidi input hygiene. Stateless env-credential auth (WEKNORA_API_KEY / WEKNORA_TOKEN + WEKNORA_HOST) for headless/CI/agent use. A curated read-only MCP tool surface (`mcp serve`) and embedded Agent Skills (`skills install`). Extensive unit + contract-golden tests and CI.
159 lines
6.3 KiB
Go
159 lines
6.3 KiB
Go
package kb
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"strings"
|
|
|
|
"github.com/spf13/cobra"
|
|
|
|
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
|
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
|
sdk "github.com/Tencent/WeKnora/client"
|
|
)
|
|
|
|
// kbInitFields enumerates the fields surfaced for `--format json` discovery on
|
|
// `kb init`. The result is the resulting InitializationConfig (read back).
|
|
var kbInitFields = []string{
|
|
"chat_model_id", "embedding_model_id", "rerank_model_id", "multimodal_id",
|
|
}
|
|
|
|
type InitOptions struct {
|
|
ChatModel string
|
|
EmbeddingModel string
|
|
Yes bool
|
|
DryRun bool
|
|
}
|
|
|
|
// InitService is the narrow SDK surface this command depends on. SetKBModelConfig
|
|
// points the KB at already-registered models; GetInitializationConfig re-reads
|
|
// the server's resulting state so the success envelope reflects what stuck.
|
|
type InitService interface {
|
|
SetKBModelConfig(ctx context.Context, kbID string, cfg *sdk.KBModelConfig) error
|
|
GetInitializationConfig(ctx context.Context, kbID string) (*sdk.InitializationConfig, error)
|
|
}
|
|
|
|
// NewCmdInit builds `weknora kb init <kb-id>` — bind models to a knowledge base
|
|
// so it becomes usable for retrieval and generation.
|
|
func NewCmdInit(f *cmdutil.Factory) *cobra.Command {
|
|
opts := &InitOptions{}
|
|
cmd := &cobra.Command{
|
|
Use: "init <kb-id>",
|
|
Short: "Configure a knowledge base's models (make it usable)",
|
|
Long: `Bind already-registered models to a knowledge base so it can embed, retrieve,
|
|
and generate. Both --chat-model (LLM, used for generation/summary) and
|
|
--embedding-model (used for retrieval) are required; register models first with
|
|
'weknora model create' and discover ids with 'weknora model list'.
|
|
|
|
High-risk write: changing a KB's embedding model affects how its content is
|
|
indexed and searched (and the server refuses once the KB has documents).
|
|
Without -y/--yes in a non-TTY / JSON context it exits 10
|
|
(input.confirmation_required) without applying the change.`,
|
|
Args: cobra.ExactArgs(1),
|
|
RunE: func(c *cobra.Command, args []string) error {
|
|
fopts, err := cmdutil.CheckFormatFlag(c)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
|
opts.Yes, _ = c.Flags().GetBool("yes")
|
|
kbID := args[0]
|
|
// Validate required flags before the dry-run gate so --dry-run rejects
|
|
// identically to the live path.
|
|
if err := validateInitFlags(opts); err != nil {
|
|
return err
|
|
}
|
|
if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
|
|
Action: "kb.init",
|
|
Args: map[string]any{"kb": kbID, "chat_model": opts.ChatModel, "embedding_model": opts.EmbeddingModel},
|
|
}); handled {
|
|
return err
|
|
}
|
|
cli, err := f.Client()
|
|
if err != nil {
|
|
return err
|
|
}
|
|
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(),
|
|
"configure", "knowledge base", kbID, "kb.init",
|
|
cmdutil.BuildRetryArgv(c, []string{"weknora", "kb", "init", kbID}, "chat-model", "embedding-model", "format")); err != nil {
|
|
return err
|
|
}
|
|
// Resolve name-or-id for the model flags (a UUID passes through; a
|
|
// name is looked up among models of the expected type). Network read
|
|
// on the live path only — the dry-run above shows the raw refs.
|
|
if opts.ChatModel, err = cmdutil.ResolveModelRef(c.Context(), cli, opts.ChatModel, "KnowledgeQA"); err != nil {
|
|
return err
|
|
}
|
|
if opts.EmbeddingModel, err = cmdutil.ResolveModelRef(c.Context(), cli, opts.EmbeddingModel, "Embedding"); err != nil {
|
|
return err
|
|
}
|
|
return runInit(c.Context(), opts, fopts, cli, kbID)
|
|
},
|
|
}
|
|
cmd.Flags().StringVar(&opts.ChatModel, "chat-model", "", "Chat / LLM model id or name for generation & summary (required) — see `weknora model list`")
|
|
cmd.Flags().StringVar(&opts.EmbeddingModel, "embedding-model", "", "Embedding model id or name for retrieval (required) — see `weknora model list`")
|
|
cmdutil.AddFormatFlag(cmd, kbInitFields...)
|
|
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
|
cmdutil.SetRisk(cmd, "kb.init")
|
|
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
|
UsedFor: "bind models to a KB so it becomes usable. --chat-model and --embedding-model are required and accept a model id or name; discover them with `weknora model list`.",
|
|
RequiredFlags: []string{"<kb-id> (positional)", "--chat-model", "--embedding-model"},
|
|
Examples: []string{
|
|
"weknora kb init kb_abc --chat-model model_llm --embedding-model model_emb -y",
|
|
},
|
|
Output: "envelope.data is the resulting {chat_model_id, embedding_model_id, rerank_model_id, multimodal_id}",
|
|
Warnings: []string{
|
|
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
|
"The server refuses to change the embedding model of a KB that already has documents.",
|
|
},
|
|
})
|
|
return cmd
|
|
}
|
|
|
|
func validateInitFlags(opts *InitOptions) error {
|
|
var missing []string
|
|
if strings.TrimSpace(opts.ChatModel) == "" {
|
|
missing = append(missing, "--chat-model")
|
|
}
|
|
if strings.TrimSpace(opts.EmbeddingModel) == "" {
|
|
missing = append(missing, "--embedding-model")
|
|
}
|
|
if len(missing) == 0 {
|
|
return nil
|
|
}
|
|
return &cmdutil.Error{
|
|
Code: cmdutil.CodeInputMissingFlag,
|
|
Message: "kb init requires " + strings.Join(missing, " and "),
|
|
Hint: "discover model ids with `weknora model list` (or register one with `weknora model create`), then pass --chat-model <id> --embedding-model <id>",
|
|
}
|
|
}
|
|
|
|
|
|
func runInit(ctx context.Context, opts *InitOptions, fopts *cmdutil.FormatOptions, svc InitService, kbID string) error {
|
|
if err := validateInitFlags(opts); err != nil {
|
|
return err
|
|
}
|
|
cfg := &sdk.KBModelConfig{
|
|
LLMModelID: opts.ChatModel,
|
|
EmbeddingModelID: opts.EmbeddingModel,
|
|
}
|
|
if err := svc.SetKBModelConfig(ctx, kbID, cfg); err != nil {
|
|
return cmdutil.WrapHTTP(err, "configure knowledge base %q", kbID)
|
|
}
|
|
// Re-read the server's resulting state so the envelope reflects what stuck.
|
|
result, err := svc.GetInitializationConfig(ctx, kbID)
|
|
if err != nil || result == nil {
|
|
// The write succeeded; surface what we applied if the read-back failed.
|
|
result = &sdk.InitializationConfig{ChatModelID: opts.ChatModel, EmbeddingModelID: opts.EmbeddingModel}
|
|
}
|
|
if fopts.WantsJSON() {
|
|
return fopts.Emit(iostreams.IO.Out, result, nil)
|
|
}
|
|
fmt.Fprintf(iostreams.IO.Out, "✓ Configured knowledge base %s (chat: %s, embedding: %s)\n",
|
|
kbID, result.ChatModelID, result.EmbeddingModelID)
|
|
return nil
|
|
}
|
|
|
|
// compile-time check: the production SDK client implements InitService.
|
|
var _ InitService = (*sdk.Client)(nil)
|