After deploying the qKnow Agent Platform, new users often encounter a confusing scenario: the system is accessible, but they aren't sure where to start.
Models might be connected, yet knowledge base parsing or knowledge graph extraction still throws errors.
Or, after entering the Bot Management page, the difference between built-in Bots and regular Bots remains unclear.
These seemingly scattered issues usually boil down to two foundational configurations:
- Is the underlying Large Language Model (LLM) connected correctly?
- Is the built-in Bot linked to an actually available model in your current environment?
For first-time qKnow users, follow this "Golden Three-Step Guide" to complete your basic setup: Configure Model → Check Bot → Verify Usage.
Step 1: Configure the Underlying LLM (Give the Platform a "Brain")
The LLM is the foundation of any agent. Before creating or using a Bot, navigate to System Management → Model Market to configure your LLM platform.
qKnow supports four common model integrations: DeepSeek, Ollama, Qwen, and OpenAI. Configuration varies by platform, so ensure you fill in the correct connection details.
Configuring API Keys:
For platforms like Qwen, you will need to generate and enter an API Key in the "Key Settings" section. You can add multiple keys for the same platform.
We highly recommend distinguishing keys based on environments, business scopes, and maintenance responsibilities to make troubleshooting easier.
Security Note:
API Keys are sensitive. Never share them in plaintext via regular documents, chat logs, or screenshots.
Verifying Model Details:
After saving the key, qKnow will automatically sync the available models for that platform.
If the model list fails to display, check the following:
- Is the API Key correct?
- Is the key still valid?
- Does the selected model platform match the key's source?
- Can your deployment environment access the model service?
- Are there extra access restrictions on the account or key?
The success criteria for this step isn't just saving the key; it's confirming that the Model Details page successfully syncs and displays available models.
Step 2: Check Built-in Bots and Link Available Models
Once your model platform is configured, you must verify the Bot's model settings. Navigate to Bot Management to view your applications.
Understanding Built-in vs. Non-Built-in Bots:
Built-in Bots are pre-configured by the system to power specific platform functions, such as knowledge graph extraction and document parsing. They are not just demo apps.
While Super Admins can customize them, proceed with caution. Do not delete nodes or drastically alter workflows unless you fully understand the system's calling relationships.
Non-built-in Bots are user-created agents designed for custom business needs. You have full freedom to configure, modify, or delete them as required.
Why Do Features Fail Even After Configuring a Model?
This is the most common pitfall for new users. The default LLM node in qKnow's built-in Bots is set to qwen-max.
If qwen-max is not configured in your Model Market or is unavailable in your environment, the built-in Bots will fail to call the model.
Having an available model in the Market does not mean the built-in Bot automatically switches to it.
How to Modify the Built-in Bot's Model:
Log in as a Super Admin, open the relevant built-in Bot, and locate the LLM node in the workflow.
If qwen-max is unavailable, change it to a conversational model that is fully configured and functional in your Model Market.
Before selecting a model, confirm it is synced, valid, suitable for the task, and accessible.
Crucially, you must save the Bot configuration after making changes. Unless you clearly understand the business logic, stick to adjusting only the unavailable model configurations.
Step 3: Perform Basic Verification
Do not assume the system is ready immediately after configuration. You must verify that the setup forms a complete chain.
- Check the Model List: Go to "Model Details" and ensure the target model is synced and available.
-
Check the Built-in Bot's LLM Node: Verify that the node is using an available model and that the default
qwen-maxhas been adjusted for your environment. - Confirm Configuration is Saved: Ensure your changes are actually saved to prevent the system from reverting to old configurations during runtime.
- Verify Business Functions: Test the actual features. Can knowledge graph extraction execute normally? Can documents be parsed? Can the Bot call the configured model?
If errors persist, troubleshoot in this order: API Key validity → Model sync success → Built-in Bot LLM selection → Configuration saved status → Network accessibility → Task-model compatibility.
The Bottom Line
For new qKnow users, deployment is only the beginning.
To get knowledge graph extraction and document parsing working, you must complete the model integration and built-in Bot configuration.
The most easily overlooked step is Step 2.
If the built-in Bot's LLM node still points to an unavailable qwen-max, platform features will fail regardless of what else you've configured.
By confirming these three links, you can eliminate repetitive troubleshooting and get qKnow into a fully operational state much faster.
Top comments (0)