docs: Add Getting Started Jupyter Notebook for new users

examples/Notebooks/Getting_Started_with_LLMWare.ipynb

@@ -0,0 +1,285 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# LLMWare 快速入门指南\\n",
+    "\\n",
+    "本 Notebook 将带你快速了解 LLMWare 的核心功能，包括：\\n",
+    "- 安装和配置\\n",
+    "- 使用模型目录\\n",
+    "- 基本推理\\n",
+    "- 函数调用\\n",
+    "\\n",
+    "> **注意**: 本 Notebook 设计为在 Jupyter 环境中运行。如果在 Colab 中运行，某些路径可能需要调整。"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. 安装 LLMWare\\n",
+    "\\n",
+    "如果你还没有安装 llmware，可以取消下面单元格的注释来安装："
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# !pip install llmware"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. 导入必要的模块"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from llmware.models import ModelCatalog\\n",
+    "from llmware.configs import LLMWareConfig\\n",
+    "\\n",
+    "# 可选：添加颜色输出\\n",
+    "try:\\n",
+    "    from colorama import Fore\\n",
+    "    BLUE = Fore.BLUE\\n",
+    "    RESET = Fore.RESET\\n",
+    "except ImportError:\\n",
+    "    BLUE = \\"\\"\\n",
+    "    RESET = \\"\\"\\n",
+    "\\n",
+    "print(f\"{BLUE}欢迎使用 LLMWare！{RESET}\")\\n",
+    "print(f\"模型将被缓存到: {BLUE}{LLMWareConfig().get_model_repo_path()}{RESET}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. 查看可用的模型\\n",
+    "\\n",
+    "LLMWare 提供了丰富的模型目录，包括：\\n",
+    "- **BLING 模型**: 用于通用文本生成\\n",
+    "- **SLIM 工具模型**: 用于特定任务的函数调用"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 获取模型目录\\n",
+    "model_catalog = ModelCatalog()\\n",
+    "\\n",
+    "# 列出所有可用的模型（仅显示前20个）\\n",
+    "all_models = model_catalog.list_all_models()\\n",
+    "print(f\"可用模型总数: {len(all_models)}\\n\")\\n",
+    "\\n",
+    "print(\"前20个模型:\")\\n",
+    "for i, model in enumerate(all_models[:20]):\\n",
+    "    print(f\"  {i+1}. {model.get('model_name', 'N/A')} - {model.get('model_family', 'N/A')}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. 基本推理示例\\n",
+    "\\n",
+    "使用 `bling-phi-3-gguf` 模型进行简单的文本生成。\\n",
+    "\\n",
+    "> **注意**: 首次运行时会下载模型，这可能需要几分钟时间。"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 加载模型\\n",
+    "print(\"正在加载 bling-phi-3-gguf 模型...\")\\n",
+    "model = ModelCatalog().load_model(\"bling-phi-3-gguf\", temperature=0.0, sample=False)\\n",
+    "\\n",
+    "# 准备提示词\\n",
+    "prompt = \"什么是 LLMWare？请用一句话简洁地解释。\"\\n",
+    "print(f\"\\n提示词: {prompt}\\n\")\\n",
+    "\\n",
+    "# 执行推理\\n",
+    "response = model.inference(prompt)\\n",
+    "print(f\"模型回答: {response['llm_response']}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. 情感分析示例\\n",
+    "\\n",
+    "使用 `slim-sentiment-tool` 模型进行情感分析。"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 加载情感分析模型\\n",
+    "print(\"正在加载 slim-sentiment-tool 模型...\\n\")\\n",
+    "sentiment_model = ModelCatalog().load_model(\"slim-sentiment-tool\", temperature=0.0, sample=False)\\n",
+    "\\n",
+    "# 测试文本\\n",
+    "test_texts = [\\n",
+    "    \"我们非常高兴能够开始使用 LLMWare！\",\\n",
+    "    \"这个产品太糟糕了，完全不能用。\",\\n",
+    "    \"这是一个普通的陈述，没有特别的情感。\"\\n",
+    "]\\n",
+    "\\n",
+    "# 对每个文本进行情感分析\\n",
+    "for text in test_texts:\\n",
+    "    print(f\"文本: {text}\")\\n",
+    "    response = sentiment_model.function_call(\\n",
+    "        text, \\n",
+    "        function=\"classify\", \\n",
+    "        params=[\"sentiment\"],\\n",
+    "        get_logits=False\\n",
+    "    )\\n",
+    "    print(f\"情感分析结果: {response}\\n\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. 命名实体识别 (NER) 示例\\n",
+    "\\n",
+    "使用 `slim-ner-tool` 模型提取文本中的命名实体。"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 加载 NER 模型\\n",
+    "print(\"正在加载 slim-ner-tool 模型...\\n\")\\n",
+    "ner_model = ModelCatalog().load_model(\"slim-ner-tool\", temperature=0.0, sample=False)\\n",
+    "\\n",
+    "# 测试文本\\n",
+    "text = \"苹果公司（Apple Inc.）于1976年由史蒂夫·乔布斯和史蒂夫·沃兹尼亚克在加利福尼亚州库比蒂诺创立。\"\\n",
+    "\\n",
+    "print(f\"文本: {text}\\n\")\\n",
+    "\\n",
+    "# 提取实体\\n",
+    "response = ner_model.function_call(\\n",
+    "    text,\\n",
+    "    function=\"classify\",\\n",
+    "    params=[\"entities\"],\\n",
+    "    get_logits=False\\n",
+    ")\\n",
+    "\\n",
+    "print(f\"识别到的实体: {response}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 7. 常见问题排查\\n",
+    "\\n",
+    "如果在使用 LLMWare 时遇到问题，请检查以下几点：\\n",
+    "\\n",
+    "1. **平台支持**: 确保你在支持的平台上运行（Mac M1/M2/M3, Linux x86, Windows）\\n",
+    "2. **模型下载**: 检查模型是否正确下载到本地缓存目录\\n",
+    "3. **内存**: 某些模型需要较大的内存，确保你的系统有足够的可用内存\\n",
+    "4. **版本**: 确保使用的是最新版本的 llmware (`pip install --upgrade llmware`)\\n",
+    "\\n",
+    "### 检查模型缓存目录"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\\n",
+    "\\n",
+    "# 获取模型缓存路径\\n",
+    "model_path = LLMWareConfig().get_model_repo_path()\\n",
+    "print(f\"模型缓存目录: {model_path}\")\\n",
+    "\\n",
+    "# 检查目录是否存在\\n",
+    "if os.path.exists(model_path):\\n",
+    "    print(f\"目录存在: ✓\")\\n",
+    "    # 列出已下载的模型\\n",
+    "    models = os.listdir(model_path)\\n",
+    "    print(f\"\\n已下载的模型 ({len(models)} 个):\")\\n",
+    "    for model in models:\\n",
+    "        print(f\"  - {model}\")\\n",
+    "else:\\n",
+    "    print(f\"目录不存在: ✗ (模型将在首次使用时自动下载)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 8. 下一步\\n",
+    "\\n",
+    "恭喜！你已经完成了 LLMWare 的快速入门。接下来你可以探索：\\n",
+    "\\n",
+    "- **更多示例**: 查看 `/examples` 目录中的其他示例\\n",
+    "- **文档**: 阅读完整的文档了解所有功能\\n",
+    "- **社区**: 加入 LLMWare 社区，与其他开发者交流\\n",
+    "\\n",
+    "### 推荐的学习路径\\n",
+    "\\n",
+    "1. **Getting_Started**: 基础概念和配置\\n",
+    "2. **Models**: 深入了解模型使用\\n",
+    "3. **Parsing**: 文档解析功能\\n",
+    "4. **Retrieval**: 检索和 RAG 功能\\n",
+    "5. **Agents**: 构建智能代理\\n",
+    "6. **Use_Cases**: 实际应用场景\\n",
+    "\\n",
+    "---\\n",
+    "\\n",
+    "**欢迎加入 LLMWare 社区！** 🚀"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}