mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-05 15:09:22 +00:00
feat: adopt directory-based docs versioning with Edge channel
Switch docs.crewai.com from navigation-only versioning (every version selector entry rendered the same docs/<lang>/* source files) to Mintlify's directory-based versioning so each version selector entry renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/* that always reflects main HEAD for unreleased work, eliminating pre-release leakage onto frozen release labels. External links to canonical /<lang>/* URLs are preserved via wildcard redirects that always land on the current default version. Layout: - docs/edge/<lang>/* rolling source (you edit here) - docs/edge/enterprise-api.*.yaml - docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots - docs/v<X.Y.Z>/enterprise-api.*.yaml - docs/images/ shared, append-only - docs/docs.json nav + redirects URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links working, and every freeze rewrites them (plus all per-section/per-page redirects) so destinations always resolve to the current default without depending on a second redirect hop. Release flow integration (devtools release): - New module crewai_devtools.docs_versioning.freeze() materialises docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the snapshot, inserts the version into every language block in docs.json, and refreshes all redirect destinations. - _update_docs_and_create_pr() in cli.py now calls that freeze during Phase 2 of devtools release. Edge changelogs are updated first (so the snapshot freeze picks them up), then the snapshot is staged alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z> — the title prefix the new CI guard reads. - The PR still gates tag, GitHub release, PyPI publish, and the enterprise release as before; no new PRs are added. - Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride Edge — and the docs PR title omits the [docs-freeze] prefix. - docs_check (AI-generated docs scaffolding) writes to docs/edge/<lang>/* so newly-generated unreleased docs land in Edge and never accidentally touch a frozen snapshot. Migration scripts (one-shot): - scripts/docs/freeze_historical_versions.py reconstructs all 16 historical snapshots (v1.10.0 .. v1.14.7) from git tags via git archive | tar, rewriting openapi: MDX refs so each snapshot reads its own enterprise-api YAML rather than the live one. - scripts/docs/prefix_version_paths.py one-shot-migrates docs.json: rewrites every page path in 16 versioned blocks to point under docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags v1.14.7 as Latest (default), prunes pages whose target file doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before v1.12.0), and writes the wildcard + per-section redirects. - scripts/docs/freeze_current_edge.py is now a thin CLI wrapper around docs_versioning.freeze for manual one-off freezes (e.g. retroactively snapshotting a forgotten release). CI guards (.github/workflows/docs-snapshots.yml): - Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose title contains [docs-freeze] (i.e. release-cut PRs generated by devtools release or the manual wrapper) may modify them. - Images under docs/images/ are append-only since snapshots share a single image directory. Deleting or renaming an image breaks every historical snapshot that still references it. Restored docs/images/crewai-otel-export.png from PR #3673; it was deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference it. Restoring instead of editing the snapshots preserves historical rendering fidelity and validates the new append-only rule retroactively. Tests: - lib/devtools/tests/test_docs_versioning.py covers the freeze: file copy, openapi rewrite, version insertion, default demotion, redirect upserts, per-section redirect rewriting, idempotency, and invalid inputs. Verified locally with mintlify broken-links: 0 broken links across the full site (Edge + 16 frozen versions, 4 locales). AGENTS.md (repo root) is the contributor guide for the new model; RELEASING.md is the release-cut runbook; README's Contribution section links to both. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Lucas Gomide
92
docs/edge/ar/tools/file-document/csvsearchtool.mdx
Normal file
92
docs/edge/ar/tools/file-document/csvsearchtool.mdx
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
title: بحث RAG في CSV
|
||||
description: أداة `CSVSearchTool` هي أداة RAG (الاسترجاع المعزز بالتوليد) قوية مصممة لعمليات البحث الدلالي داخل محتوى ملف CSV.
|
||||
icon: file-csv
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `CSVSearchTool`
|
||||
|
||||
<Note>
|
||||
**تجريبية**: لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل.
|
||||
</Note>
|
||||
|
||||
## الوصف
|
||||
|
||||
تُستخدم هذه الأداة لإجراء بحث RAG (الاسترجاع المعزز بالتوليد) داخل محتوى ملف CSV. تتيح للمستخدمين البحث دلالياً عن استعلامات في محتوى ملف CSV محدد. هذه الميزة مفيدة بشكل خاص لاستخراج المعلومات من مجموعات بيانات CSV الكبيرة حيث قد تكون طرق البحث التقليدية غير فعالة. جميع الأدوات التي تحتوي على "Search" في اسمها، بما في ذلك CSVSearchTool، هي أدوات RAG مصممة للبحث في مصادر بيانات مختلفة.
|
||||
|
||||
## التثبيت
|
||||
|
||||
قم بتثبيت حزمة crewai_tools
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## مثال
|
||||
|
||||
```python Code
|
||||
from crewai_tools import CSVSearchTool
|
||||
|
||||
# Initialize the tool with a specific CSV file.
|
||||
# This setup allows the agent to only search the given CSV file.
|
||||
tool = CSVSearchTool(csv='path/to/your/csvfile.csv')
|
||||
|
||||
# OR
|
||||
|
||||
# Initialize the tool without a specific CSV file.
|
||||
# Agent will need to provide the CSV path at runtime.
|
||||
tool = CSVSearchTool()
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
|
||||
يمكن استخدام المعاملات التالية لتخصيص سلوك `CSVSearchTool`:
|
||||
|
||||
| المعامل | النوع | الوصف |
|
||||
|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| **csv** | `string` | _اختياري_. مسار ملف CSV المراد البحث فيه. هذا معامل إلزامي إذا تمت تهيئة الأداة بدون ملف CSV محدد؛ وإلا فهو اختياري. |
|
||||
|
||||
## النموذج والتضمينات المخصصة
|
||||
|
||||
بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي:
|
||||
|
||||
```python Code
|
||||
from chromadb.config import Settings
|
||||
|
||||
tool = CSVSearchTool(
|
||||
config={
|
||||
"embedding_model": {
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "text-embedding-3-small",
|
||||
# "api_key": "sk-...",
|
||||
},
|
||||
},
|
||||
"vectordb": {
|
||||
"provider": "chromadb", # or "qdrant"
|
||||
"config": {
|
||||
# "settings": Settings(persist_directory="/content/chroma", allow_reset=True, is_persistent=True),
|
||||
# from qdrant_client.models import VectorParams, Distance
|
||||
# "vectors_config": VectorParams(size=384, distance=Distance.COSINE),
|
||||
}
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## الأمان
|
||||
|
||||
### التحقق من صحة المسارات
|
||||
|
||||
يتم التحقق من مسارات الملفات المقدمة لهذه الأداة مقابل مجلد العمل الحالي. يتم رفض المسارات التي تحل خارج مجلد العمل وإطلاق `ValueError`.
|
||||
|
||||
للسماح بالمسارات خارج مجلد العمل (مثلاً في الاختبارات أو خطوط الأنابيب الموثوقة)، عيّن متغير البيئة التالي:
|
||||
|
||||
```shell
|
||||
CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true
|
||||
```
|
||||
|
||||
### التحقق من صحة الروابط
|
||||
|
||||
يتم التحقق من مدخلات الروابط: يتم حظر مخطط `file://` والطلبات التي تستهدف نطاقات IP الخاصة أو المحجوزة لمنع هجمات تزوير الطلبات من جانب الخادم (SSRF).
|
||||
52
docs/edge/ar/tools/file-document/directoryreadtool.mdx
Normal file
52
docs/edge/ar/tools/file-document/directoryreadtool.mdx
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: قراءة المجلدات
|
||||
description: أداة `DirectoryReadTool` هي أداة مساعدة قوية مصممة لتوفير قائمة شاملة بمحتويات المجلد.
|
||||
icon: folder-tree
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `DirectoryReadTool`
|
||||
|
||||
<Note>
|
||||
لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل.
|
||||
</Note>
|
||||
|
||||
## الوصف
|
||||
|
||||
أداة DirectoryReadTool هي أداة مساعدة قوية مصممة لتوفير قائمة شاملة بمحتويات المجلد. يمكنها التنقل بشكل متكرر عبر المجلد المحدد، مما يوفر للمستخدمين تعداداً مفصلاً لجميع الملفات، بما في ذلك تلك الموجودة داخل المجلدات الفرعية. هذه الأداة ضرورية للمهام التي تتطلب جرداً شاملاً لهياكل المجلدات أو للتحقق من تنظيم الملفات داخل المجلدات.
|
||||
|
||||
## التثبيت
|
||||
|
||||
لاستخدام DirectoryReadTool في مشروعك، قم بتثبيت حزمة `crewai_tools`. إذا لم تكن هذه الحزمة جزءاً من بيئتك بعد، يمكنك تثبيتها باستخدام pip بالأمر التالي:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
يُثبّت هذا الأمر أحدث إصدار من حزمة `crewai_tools`، مما يمنح الوصول إلى DirectoryReadTool بالإضافة إلى أدوات مساعدة أخرى.
|
||||
|
||||
## مثال
|
||||
|
||||
استخدام DirectoryReadTool بسيط ومباشر. يوضح مقتطف الكود التالي كيفية إعدادها واستخدام الأداة لعرض محتويات مجلد محدد:
|
||||
|
||||
```python Code
|
||||
from crewai_tools import DirectoryReadTool
|
||||
|
||||
# Initialize the tool so the agent can read any directory's content
|
||||
# it learns about during execution
|
||||
tool = DirectoryReadTool()
|
||||
|
||||
# OR
|
||||
|
||||
# Initialize the tool with a specific directory,
|
||||
# so the agent can only read the content of the specified directory
|
||||
tool = DirectoryReadTool(directory='/path/to/your/directory')
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
|
||||
يمكن استخدام المعاملات التالية لتخصيص سلوك `DirectoryReadTool`:
|
||||
|
||||
| المعامل | النوع | الوصف |
|
||||
|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| **directory** | `string` | _اختياري_. معامل يحدد المسار إلى المجلد الذي ترغب في عرض محتوياته. يقبل كلاً من المسارات المطلقة والنسبية، ويوجه الأداة إلى المجلد المطلوب لعرض المحتوى. |
|
||||
82
docs/edge/ar/tools/file-document/directorysearchtool.mdx
Normal file
82
docs/edge/ar/tools/file-document/directorysearchtool.mdx
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: بحث RAG في المجلدات
|
||||
description: أداة `DirectorySearchTool` هي أداة RAG (الاسترجاع المعزز بالتوليد) قوية مصممة لعمليات البحث الدلالي داخل محتوى المجلد.
|
||||
icon: address-book
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `DirectorySearchTool`
|
||||
|
||||
<Note>
|
||||
**تجريبية**: أداة DirectorySearchTool قيد التطوير المستمر. قد تُضاف ميزات أو تُزال، وقد يتغير الأداء بشكل غير متوقع أثناء تحسين الأداة.
|
||||
</Note>
|
||||
|
||||
## الوصف
|
||||
|
||||
تتيح DirectorySearchTool البحث الدلالي داخل محتوى المجلدات المحددة، مستفيدة من منهجية الاسترجاع المعزز بالتوليد (RAG) للتنقل الفعال بين الملفات. صُممت لتكون مرنة، حيث تسمح للمستخدمين بتحديد مجلدات البحث ديناميكياً أثناء التشغيل أو تعيين مجلد ثابت أثناء الإعداد الأولي.
|
||||
|
||||
## التثبيت
|
||||
|
||||
لاستخدام DirectorySearchTool، ابدأ بتثبيت حزمة crewai_tools. نفّذ الأمر التالي في الطرفية:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## التهيئة والاستخدام
|
||||
|
||||
قم باستيراد DirectorySearchTool من حزمة `crewai_tools` للبدء. يمكنك تهيئة الأداة بدون تحديد مجلد، مما يتيح تعيين مجلد البحث أثناء التشغيل. بدلاً من ذلك، يمكن تهيئة الأداة بمجلد محدد مسبقاً.
|
||||
|
||||
```python Code
|
||||
from crewai_tools import DirectorySearchTool
|
||||
|
||||
# For dynamic directory specification at runtime
|
||||
tool = DirectorySearchTool()
|
||||
|
||||
# For fixed directory searches
|
||||
tool = DirectorySearchTool(directory='/path/to/directory')
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
|
||||
- `directory`: معامل نصي يحدد مجلد البحث. هذا اختياري أثناء التهيئة لكنه مطلوب لعمليات البحث إذا لم يتم تعيينه مبدئياً.
|
||||
|
||||
## النموذج والتضمينات المخصصة
|
||||
|
||||
تستخدم DirectorySearchTool افتراضياً OpenAI للتضمينات والتلخيص. تتضمن خيارات التخصيص لهذه الإعدادات تغيير مزود النموذج والتكوين، مما يعزز المرونة للمستخدمين المتقدمين.
|
||||
|
||||
```python Code
|
||||
from chromadb.config import Settings
|
||||
|
||||
tool = DirectorySearchTool(
|
||||
config={
|
||||
"embedding_model": {
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "text-embedding-3-small",
|
||||
# "api_key": "sk-...",
|
||||
},
|
||||
},
|
||||
"vectordb": {
|
||||
"provider": "chromadb", # or "qdrant"
|
||||
"config": {
|
||||
# "settings": Settings(persist_directory="/content/chroma", allow_reset=True, is_persistent=True),
|
||||
# from qdrant_client.models import VectorParams, Distance
|
||||
# "vectors_config": VectorParams(size=384, distance=Distance.COSINE),
|
||||
}
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## الأمان
|
||||
|
||||
### التحقق من صحة المسارات
|
||||
|
||||
يتم التحقق من مسارات المجلدات المقدمة لهذه الأداة مقابل مجلد العمل الحالي. يتم رفض المسارات التي تحل خارج مجلد العمل وإطلاق `ValueError`.
|
||||
|
||||
للسماح بالمسارات خارج مجلد العمل (مثلاً في الاختبارات أو خطوط الأنابيب الموثوقة)، عيّن متغير البيئة التالي:
|
||||
|
||||
```shell
|
||||
CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true
|
||||
```
|
||||
77
docs/edge/ar/tools/file-document/docxsearchtool.mdx
Normal file
77
docs/edge/ar/tools/file-document/docxsearchtool.mdx
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: بحث RAG في DOCX
|
||||
description: أداة `DOCXSearchTool` هي أداة RAG مصممة للبحث الدلالي داخل مستندات DOCX.
|
||||
icon: file-word
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `DOCXSearchTool`
|
||||
|
||||
<Note>
|
||||
لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل.
|
||||
</Note>
|
||||
|
||||
## الوصف
|
||||
|
||||
أداة `DOCXSearchTool` هي أداة RAG مصممة للبحث الدلالي داخل مستندات DOCX. تتيح للمستخدمين البحث بفعالية واستخراج المعلومات ذات الصلة من ملفات DOCX باستخدام عمليات بحث قائمة على الاستعلامات. هذه الأداة لا تُقدَّر بثمن لمهام تحليل البيانات وإدارة المعلومات والبحث، حيث تبسط عملية العثور على معلومات محددة داخل مجموعات مستندات كبيرة.
|
||||
|
||||
## التثبيت
|
||||
|
||||
قم بتثبيت حزمة crewai_tools بتنفيذ الأمر التالي في الطرفية:
|
||||
|
||||
```shell
|
||||
uv pip install docx2txt 'crewai[tools]'
|
||||
```
|
||||
|
||||
## مثال
|
||||
|
||||
يوضح المثال التالي تهيئة DOCXSearchTool للبحث داخل محتوى أي ملف DOCX أو بمسار ملف DOCX محدد.
|
||||
|
||||
```python Code
|
||||
from crewai_tools import DOCXSearchTool
|
||||
|
||||
# Initialize the tool to search within any DOCX file's content
|
||||
tool = DOCXSearchTool()
|
||||
|
||||
# OR
|
||||
|
||||
# Initialize the tool with a specific DOCX file,
|
||||
# so the agent can only search the content of the specified DOCX file
|
||||
tool = DOCXSearchTool(docx='path/to/your/document.docx')
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
|
||||
يمكن استخدام المعاملات التالية لتخصيص سلوك `DOCXSearchTool`:
|
||||
|
||||
| المعامل | النوع | الوصف |
|
||||
|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| **docx** | `string` | _اختياري_. معامل يحدد مسار ملف DOCX المراد البحث فيه. إذا لم يُقدَّم أثناء التهيئة، تسمح الأداة بتحديد مسار محتوى أي ملف DOCX للبحث لاحقاً. |
|
||||
|
||||
## النموذج والتضمينات المخصصة
|
||||
|
||||
بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي:
|
||||
|
||||
```python Code
|
||||
from chromadb.config import Settings
|
||||
|
||||
tool = DOCXSearchTool(
|
||||
config={
|
||||
"embedding_model": {
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "text-embedding-3-small",
|
||||
# "api_key": "sk-...",
|
||||
},
|
||||
},
|
||||
"vectordb": {
|
||||
"provider": "chromadb", # or "qdrant"
|
||||
"config": {
|
||||
# "settings": Settings(persist_directory="/content/chroma", allow_reset=True, is_persistent=True),
|
||||
# from qdrant_client.models import VectorParams, Distance
|
||||
# "vectors_config": VectorParams(size=384, distance=Distance.COSINE),
|
||||
}
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
42
docs/edge/ar/tools/file-document/filereadtool.mdx
Normal file
42
docs/edge/ar/tools/file-document/filereadtool.mdx
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: قراءة الملفات
|
||||
description: أداة `FileReadTool` مصممة لقراءة الملفات من نظام الملفات المحلي.
|
||||
icon: folders
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## نظرة عامة
|
||||
|
||||
<Note>
|
||||
لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل.
|
||||
</Note>
|
||||
|
||||
تمثل أداة FileReadTool مفهومياً مجموعة من الوظائف ضمن حزمة crewai_tools تهدف إلى تسهيل قراءة الملفات واسترجاع المحتوى. تتضمن هذه المجموعة أدوات لمعالجة ملفات نصية دفعية، وقراءة ملفات التكوين أثناء التشغيل، واستيراد البيانات للتحليلات. تدعم مجموعة متنوعة من صيغ الملفات النصية مثل `.txt` و `.csv` و `.json` وغيرها. اعتماداً على نوع الملف، توفر المجموعة وظائف متخصصة، مثل تحويل محتوى JSON إلى قاموس Python لسهولة الاستخدام.
|
||||
|
||||
## التثبيت
|
||||
|
||||
لاستخدام الوظائف المنسوبة سابقاً لأداة FileReadTool، قم بتثبيت حزمة crewai_tools:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## مثال على الاستخدام
|
||||
|
||||
للبدء مع FileReadTool:
|
||||
|
||||
```python Code
|
||||
from crewai_tools import FileReadTool
|
||||
|
||||
# Initialize the tool to read any files the agents knows or lean the path for
|
||||
file_read_tool = FileReadTool()
|
||||
|
||||
# OR
|
||||
|
||||
# Initialize the tool with a specific file path, so the agent can only read the content of the specified file
|
||||
file_read_tool = FileReadTool(file_path='path/to/your/file.txt')
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
|
||||
- `file_path`: مسار الملف المراد قراءته. يقبل كلاً من المسارات المطلقة والنسبية. تأكد من وجود الملف وأن لديك الصلاحيات اللازمة للوصول إليه.
|
||||
47
docs/edge/ar/tools/file-document/filewritetool.mdx
Normal file
47
docs/edge/ar/tools/file-document/filewritetool.mdx
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: كتابة الملفات
|
||||
description: أداة `FileWriterTool` مصممة لكتابة المحتوى في الملفات.
|
||||
icon: file-pen
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `FileWriterTool`
|
||||
|
||||
## الوصف
|
||||
|
||||
أداة `FileWriterTool` هي مكوّن من حزمة crewai_tools، مصممة لتبسيط عملية كتابة المحتوى في الملفات مع توافق عبر المنصات (Windows و Linux و macOS). تكون مفيدة بشكل خاص في سيناريوهات مثل توليد التقارير وحفظ السجلات وإنشاء ملفات التكوين والمزيد. تتعامل هذه الأداة مع اختلافات المسارات عبر أنظمة التشغيل، وتدعم ترميز UTF-8، وتنشئ المجلدات تلقائياً إذا لم تكن موجودة، مما يسهل تنظيم المخرجات بشكل موثوق عبر المنصات المختلفة.
|
||||
|
||||
## التثبيت
|
||||
|
||||
قم بتثبيت حزمة crewai_tools لاستخدام `FileWriterTool` في مشاريعك:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## مثال
|
||||
|
||||
للبدء مع `FileWriterTool`:
|
||||
|
||||
```python Code
|
||||
from crewai_tools import FileWriterTool
|
||||
|
||||
# Initialize the tool
|
||||
file_writer_tool = FileWriterTool()
|
||||
|
||||
# Write content to a file in a specified directory
|
||||
result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory')
|
||||
print(result)
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
|
||||
- `filename`: اسم الملف الذي تريد إنشاءه أو الكتابة فوقه.
|
||||
- `content`: المحتوى المراد كتابته في الملف.
|
||||
- `directory` (اختياري): مسار المجلد حيث سيتم إنشاء الملف. الافتراضي هو المجلد الحالي (`.`). إذا لم يكن المجلد موجوداً، سيتم إنشاؤه.
|
||||
|
||||
## الخلاصة
|
||||
|
||||
من خلال دمج `FileWriterTool` في أطقمك، يمكن للوكلاء كتابة المحتوى في الملفات بشكل موثوق عبر أنظمة التشغيل المختلفة. هذه الأداة ضرورية للمهام التي تتطلب حفظ بيانات المخرجات وإنشاء أنظمة ملفات منظمة والتعامل مع عمليات الملفات عبر المنصات. يُوصى بها بشكل خاص لمستخدمي Windows الذين قد يواجهون مشكلات في كتابة الملفات مع عمليات ملفات Python القياسية.
|
||||
|
||||
من خلال الالتزام بإرشادات الإعداد والاستخدام المقدمة، فإن دمج هذه الأداة في المشاريع أمر مباشر ويضمن سلوكاً متسقاً لكتابة الملفات عبر جميع المنصات.
|
||||
91
docs/edge/ar/tools/file-document/jsonsearchtool.mdx
Normal file
91
docs/edge/ar/tools/file-document/jsonsearchtool.mdx
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: بحث RAG في JSON
|
||||
description: أداة `JSONSearchTool` مصممة للبحث في ملفات JSON وإرجاع النتائج الأكثر صلة.
|
||||
icon: file-code
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `JSONSearchTool`
|
||||
|
||||
<Note>
|
||||
أداة JSONSearchTool حالياً في مرحلة تجريبية. هذا يعني أن الأداة قيد التطوير
|
||||
النشط، وقد يواجه المستخدمون سلوكاً غير متوقع أو تغييرات. نشجع بشدة التعليقات
|
||||
حول أي مشكلات أو اقتراحات للتحسين.
|
||||
</Note>
|
||||
|
||||
## الوصف
|
||||
|
||||
صُممت أداة JSONSearchTool لتسهيل عمليات البحث الفعالة والدقيقة داخل محتوى ملفات JSON. تستخدم آلية بحث RAG (الاسترجاع والتوليد)، مما يتيح للمستخدمين تحديد مسار JSON لعمليات بحث مستهدفة داخل ملف JSON معين. تحسّن هذه القدرة بشكل ملحوظ دقة نتائج البحث وصلتها.
|
||||
|
||||
## التثبيت
|
||||
|
||||
لتثبيت JSONSearchTool، استخدم أمر pip التالي:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## أمثلة على الاستخدام
|
||||
|
||||
فيما يلي أمثلة محدّثة حول كيفية استخدام JSONSearchTool بفعالية للبحث داخل ملفات JSON. تأخذ هذه الأمثلة بعين الاعتبار التنفيذ الحالي وأنماط الاستخدام المحددة في قاعدة الكود.
|
||||
|
||||
```python Code
|
||||
from crewai_tools import JSONSearchTool
|
||||
|
||||
# General JSON content search
|
||||
# This approach is suitable when the JSON path is either known beforehand or can be dynamically identified.
|
||||
tool = JSONSearchTool()
|
||||
|
||||
# Restricting search to a specific JSON file
|
||||
# Use this initialization method when you want to limit the search scope to a specific JSON file.
|
||||
tool = JSONSearchTool(json_path='./path/to/your/file.json')
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
|
||||
- `json_path` (str, اختياري): يحدد مسار ملف JSON المراد البحث فيه. هذا المعامل غير مطلوب إذا تمت تهيئة الأداة لبحث عام. عند تقديمه، يقتصر البحث على ملف JSON المحدد.
|
||||
|
||||
## خيارات التكوين
|
||||
|
||||
تدعم أداة JSONSearchTool تخصيصاً واسعاً من خلال قاموس تكوين. يتيح هذا للمستخدمين اختيار نماذج مختلفة للتضمينات والتلخيص بناءً على متطلباتهم.
|
||||
|
||||
```python Code
|
||||
tool = JSONSearchTool(
|
||||
config={
|
||||
"llm": {
|
||||
"provider": "ollama", # Other options include google, openai, anthropic, llama2, etc.
|
||||
"config": {
|
||||
"model": "llama2",
|
||||
# Additional optional configurations can be specified here.
|
||||
# temperature=0.5,
|
||||
# top_p=1,
|
||||
# stream=true,
|
||||
},
|
||||
},
|
||||
"embedding_model": {
|
||||
"provider": "google-generativeai", # or openai, ollama, ...
|
||||
"config": {
|
||||
"model_name": "gemini-embedding-001",
|
||||
"task_type": "RETRIEVAL_DOCUMENT",
|
||||
# Further customization options can be added here.
|
||||
},
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## الأمان
|
||||
|
||||
### التحقق من صحة المسارات
|
||||
|
||||
يتم التحقق من مسارات الملفات المقدمة لهذه الأداة مقابل مجلد العمل الحالي. يتم رفض المسارات التي تحل خارج مجلد العمل وإطلاق `ValueError`.
|
||||
|
||||
للسماح بالمسارات خارج مجلد العمل (مثلاً في الاختبارات أو خطوط الأنابيب الموثوقة)، عيّن متغير البيئة التالي:
|
||||
|
||||
```shell
|
||||
CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true
|
||||
```
|
||||
|
||||
### التحقق من صحة الروابط
|
||||
|
||||
يتم التحقق من مدخلات الروابط: يتم حظر مخطط `file://` والطلبات التي تستهدف نطاقات IP الخاصة أو المحجوزة لمنع هجمات تزوير الطلبات من جانب الخادم (SSRF).
|
||||
72
docs/edge/ar/tools/file-document/mdxsearchtool.mdx
Normal file
72
docs/edge/ar/tools/file-document/mdxsearchtool.mdx
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: بحث RAG في MDX
|
||||
description: أداة `MDXSearchTool` مصممة للبحث في ملفات MDX وإرجاع النتائج الأكثر صلة.
|
||||
icon: markdown
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `MDXSearchTool`
|
||||
|
||||
<Note>
|
||||
أداة MDXSearchTool في تطوير مستمر. قد تُضاف ميزات أو تُزال، وقد تتغير الوظائف بشكل غير متوقع أثناء تحسين الأداة.
|
||||
</Note>
|
||||
|
||||
## الوصف
|
||||
|
||||
أداة البحث في MDX هي مكوّن من حزمة `crewai_tools` يهدف إلى تسهيل استخراج لغة Markdown المتقدمة. تتيح للمستخدمين البحث بفعالية واستخراج المعلومات ذات الصلة من ملفات MD باستخدام عمليات بحث قائمة على الاستعلامات. هذه الأداة لا تُقدَّر بثمن لمهام تحليل البيانات وإدارة المعلومات والبحث، حيث تبسط عملية العثور على معلومات محددة داخل مجموعات مستندات كبيرة.
|
||||
|
||||
## التثبيت
|
||||
|
||||
قبل استخدام أداة البحث في MDX، تأكد من تثبيت حزمة `crewai_tools`. إذا لم تكن مثبتة، يمكنك تثبيتها بالأمر التالي:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## مثال على الاستخدام
|
||||
|
||||
لاستخدام أداة البحث في MDX، يجب أولاً إعداد متغيرات البيئة اللازمة. ثم قم بدمج الأداة في مشروع crewAI الخاص بك لبدء أبحاث السوق. فيما يلي مثال أساسي لكيفية القيام بذلك:
|
||||
|
||||
```python Code
|
||||
from crewai_tools import MDXSearchTool
|
||||
|
||||
# Initialize the tool to search any MDX content it learns about during execution
|
||||
tool = MDXSearchTool()
|
||||
|
||||
# OR
|
||||
|
||||
# Initialize the tool with a specific MDX file path for an exclusive search within that document
|
||||
tool = MDXSearchTool(mdx='path/to/your/document.mdx')
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
|
||||
- mdx: **اختياري**. يحدد مسار ملف MDX للبحث. يمكن تقديمه أثناء التهيئة.
|
||||
|
||||
## تخصيص النموذج والتضمينات
|
||||
|
||||
تستخدم الأداة افتراضياً OpenAI للتضمينات والتلخيص. للتخصيص، استخدم قاموس تكوين كما هو موضح أدناه:
|
||||
|
||||
```python Code
|
||||
from chromadb.config import Settings
|
||||
|
||||
tool = MDXSearchTool(
|
||||
config={
|
||||
"embedding_model": {
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "text-embedding-3-small",
|
||||
# "api_key": "sk-...",
|
||||
},
|
||||
},
|
||||
"vectordb": {
|
||||
"provider": "chromadb", # or "qdrant"
|
||||
"config": {
|
||||
# "settings": Settings(persist_directory="/content/chroma", allow_reset=True, is_persistent=True),
|
||||
# from qdrant_client.models import VectorParams, Distance
|
||||
# "vectors_config": VectorParams(size=384, distance=Distance.COSINE),
|
||||
}
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
88
docs/edge/ar/tools/file-document/ocrtool.mdx
Normal file
88
docs/edge/ar/tools/file-document/ocrtool.mdx
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: أداة OCR
|
||||
description: تستخرج `OCRTool` النص من الصور المحلية أو عناوين URL للصور باستخدام نموذج LLM مزود بالرؤية.
|
||||
icon: image
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `OCRTool`
|
||||
|
||||
## الوصف
|
||||
|
||||
استخراج النص من الصور (مسار محلي أو عنوان URL). تستخدم نموذج LLM مزوداً بالرؤية عبر واجهة LLM الخاصة بـ CrewAI.
|
||||
|
||||
## التثبيت
|
||||
|
||||
لا حاجة لتثبيت إضافي بخلاف `crewai-tools`. تأكد من أن النموذج المحدد يدعم الرؤية.
|
||||
|
||||
## المعاملات
|
||||
|
||||
### معاملات التشغيل
|
||||
|
||||
- `image_path_url` (str, مطلوب): مسار صورة محلية أو عنوان URL بروتوكول HTTP(S).
|
||||
|
||||
## أمثلة
|
||||
|
||||
### الاستخدام المباشر
|
||||
|
||||
```python Code
|
||||
from crewai_tools import OCRTool
|
||||
|
||||
print(OCRTool().run(image_path_url="/tmp/receipt.png"))
|
||||
```
|
||||
|
||||
### مع وكيل
|
||||
|
||||
```python Code
|
||||
from crewai import Agent, Task, Crew
|
||||
from crewai_tools import OCRTool
|
||||
|
||||
ocr = OCRTool()
|
||||
|
||||
agent = Agent(
|
||||
role="OCR",
|
||||
goal="Extract text",
|
||||
tools=[ocr],
|
||||
)
|
||||
|
||||
task = Task(
|
||||
description="Extract text from https://example.com/invoice.jpg",
|
||||
expected_output="All detected text in plain text",
|
||||
agent=agent,
|
||||
)
|
||||
|
||||
crew = Crew(agents=[agent], tasks=[task])
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
## ملاحظات
|
||||
|
||||
- تأكد من أن النموذج المحدد يدعم مدخلات الصور.
|
||||
- للصور الكبيرة، فكر في تصغير الحجم لتقليل استهلاك الرموز.
|
||||
- يمكنك تمرير نسخة LLM محددة للأداة (مثل `LLM(model="gpt-4o")`) إذا لزم الأمر، وفقاً لتوجيهات README.
|
||||
|
||||
## مثال
|
||||
|
||||
```python Code
|
||||
from crewai import Agent, Task, Crew
|
||||
from crewai_tools import OCRTool
|
||||
|
||||
tool = OCRTool()
|
||||
|
||||
agent = Agent(
|
||||
role="OCR Specialist",
|
||||
goal="Extract text from images",
|
||||
backstory="Vision‑enabled analyst",
|
||||
tools=[tool],
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
task = Task(
|
||||
description="Extract text from https://example.com/receipt.png",
|
||||
expected_output="All detected text in plain text",
|
||||
agent=agent,
|
||||
)
|
||||
|
||||
crew = Crew(agents=[agent], tasks=[task])
|
||||
result = crew.kickoff()
|
||||
```
|
||||
97
docs/edge/ar/tools/file-document/overview.mdx
Normal file
97
docs/edge/ar/tools/file-document/overview.mdx
Normal file
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: "نظرة عامة"
|
||||
description: "قراءة وكتابة والبحث في صيغ ملفات متنوعة باستخدام أدوات معالجة المستندات من CrewAI"
|
||||
icon: "face-smile"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
تتيح هذه الأدوات لوكلائك العمل مع صيغ ملفات وأنواع مستندات متنوعة. من قراءة ملفات PDF إلى معالجة بيانات JSON، تتعامل هذه الأدوات مع جميع احتياجات معالجة المستندات الخاصة بك.
|
||||
|
||||
## **الأدوات المتاحة**
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="أداة قراءة الملفات" icon="folders" href="/ar/tools/file-document/filereadtool">
|
||||
قراءة المحتوى من أي نوع ملف بما في ذلك النصوص و Markdown والمزيد.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة كتابة الملفات" icon="file-pen" href="/ar/tools/file-document/filewritetool">
|
||||
كتابة المحتوى في الملفات وإنشاء مستندات جديدة وحفظ البيانات المعالجة.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة بحث PDF" icon="file-pdf" href="/ar/tools/file-document/pdfsearchtool">
|
||||
البحث واستخراج محتوى نصي من مستندات PDF بكفاءة.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة بحث DOCX" icon="file-word" href="/ar/tools/file-document/docxsearchtool">
|
||||
البحث في مستندات Microsoft Word واستخراج المحتوى ذي الصلة.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة بحث JSON" icon="brackets-curly" href="/ar/tools/file-document/jsonsearchtool">
|
||||
تحليل والبحث في ملفات JSON بإمكانيات استعلام متقدمة.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة بحث CSV" icon="table" href="/ar/tools/file-document/csvsearchtool">
|
||||
معالجة والبحث في ملفات CSV واستخراج صفوف وأعمدة محددة.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة بحث XML" icon="code" href="/ar/tools/file-document/xmlsearchtool">
|
||||
تحليل ملفات XML والبحث عن عناصر وخصائص محددة.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة بحث MDX" icon="markdown" href="/ar/tools/file-document/mdxsearchtool">
|
||||
البحث في ملفات MDX واستخراج المحتوى من الوثائق.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة بحث TXT" icon="file-lines" href="/ar/tools/file-document/txtsearchtool">
|
||||
البحث في ملفات النص العادي بإمكانيات مطابقة الأنماط.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة بحث المجلدات" icon="folder-open" href="/ar/tools/file-document/directorysearchtool">
|
||||
البحث عن الملفات والمجلدات داخل هياكل المجلدات.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة قراءة المجلدات" icon="folder" href="/ar/tools/file-document/directoryreadtool">
|
||||
قراءة وعرض محتويات المجلدات وهياكل الملفات والبيانات الوصفية.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة OCR" icon="image" href="/ar/tools/file-document/ocrtool">
|
||||
استخراج النص من الصور (ملفات محلية أو عناوين URL) باستخدام نموذج LLM مزود بالرؤية.
|
||||
</Card>
|
||||
|
||||
<Card title="أداة كتابة نص PDF" icon="file-pdf" href="/ar/tools/file-document/pdf-text-writing-tool">
|
||||
كتابة نص في إحداثيات محددة في ملفات PDF، مع خطوط مخصصة اختيارية.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## **حالات الاستخدام الشائعة**
|
||||
|
||||
- **معالجة المستندات**: استخراج وتحليل المحتوى من صيغ ملفات متنوعة
|
||||
- **استيراد البيانات**: قراءة بيانات منظمة من ملفات CSV و JSON و XML
|
||||
- **بحث المحتوى**: العثور على معلومات محددة داخل مجموعات مستندات كبيرة
|
||||
- **إدارة الملفات**: تنظيم ومعالجة الملفات والمجلدات
|
||||
- **تصدير البيانات**: حفظ النتائج المعالجة في صيغ ملفات متنوعة
|
||||
|
||||
## **مثال للبدء السريع**
|
||||
|
||||
```python
|
||||
from crewai_tools import FileReadTool, PDFSearchTool, JSONSearchTool
|
||||
|
||||
# Create tools
|
||||
file_reader = FileReadTool()
|
||||
pdf_searcher = PDFSearchTool()
|
||||
json_processor = JSONSearchTool()
|
||||
|
||||
# Add to your agent
|
||||
agent = Agent(
|
||||
role="Document Analyst",
|
||||
tools=[file_reader, pdf_searcher, json_processor],
|
||||
goal="Process and analyze various document types"
|
||||
)
|
||||
```
|
||||
|
||||
## **نصائح لمعالجة المستندات**
|
||||
|
||||
- **صلاحيات الملفات**: تأكد من أن وكيلك لديه صلاحيات القراءة/الكتابة المناسبة
|
||||
- **الملفات الكبيرة**: فكر في التقسيم إلى أجزاء للمستندات الكبيرة جداً
|
||||
- **دعم الصيغ**: راجع وثائق الأداة لمعرفة صيغ الملفات المدعومة
|
||||
- **معالجة الأخطاء**: طبّق معالجة أخطاء مناسبة للملفات التالفة أو التي يتعذر الوصول إليها
|
||||
75
docs/edge/ar/tools/file-document/pdf-text-writing-tool.mdx
Normal file
75
docs/edge/ar/tools/file-document/pdf-text-writing-tool.mdx
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: أداة كتابة نص PDF
|
||||
description: تكتب `PDFTextWritingTool` نصاً في مواضع محددة في ملف PDF، مع دعم الخطوط المخصصة.
|
||||
icon: file-pdf
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `PDFTextWritingTool`
|
||||
|
||||
## الوصف
|
||||
|
||||
كتابة نص في إحداثيات دقيقة على صفحة PDF، مع إمكانية تضمين خط TrueType مخصص اختيارياً.
|
||||
|
||||
## المعاملات
|
||||
|
||||
### معاملات التشغيل
|
||||
|
||||
- `pdf_path` (str, مطلوب): مسار ملف PDF المدخل.
|
||||
- `text` (str, مطلوب): النص المراد إضافته.
|
||||
- `position` (tuple[int, int], مطلوب): إحداثيات `(x, y)`.
|
||||
- `font_size` (int, الافتراضي `12`)
|
||||
- `font_color` (str, الافتراضي `"0 0 0 rg"`)
|
||||
- `font_name` (str, الافتراضي `"F1"`)
|
||||
- `font_file` (str, اختياري): مسار ملف `.ttf`.
|
||||
- `page_number` (int, الافتراضي `0`)
|
||||
|
||||
## مثال
|
||||
|
||||
```python Code
|
||||
from crewai import Agent, Task, Crew
|
||||
from crewai_tools import PDFTextWritingTool
|
||||
|
||||
tool = PDFTextWritingTool()
|
||||
|
||||
agent = Agent(
|
||||
role="PDF Editor",
|
||||
goal="Annotate PDFs",
|
||||
backstory="Documentation specialist",
|
||||
tools=[tool],
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
task = Task(
|
||||
description="Write 'CONFIDENTIAL' at (72, 720) on page 1 of ./sample.pdf",
|
||||
expected_output="Confirmation message",
|
||||
agent=agent,
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[agent],
|
||||
tasks=[task],
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
### الاستخدام المباشر
|
||||
|
||||
```python Code
|
||||
from crewai_tools import PDFTextWritingTool
|
||||
|
||||
PDFTextWritingTool().run(
|
||||
pdf_path="./input.pdf",
|
||||
text="CONFIDENTIAL",
|
||||
position=(72, 720),
|
||||
font_size=18,
|
||||
page_number=0,
|
||||
)
|
||||
```
|
||||
|
||||
## نصائح
|
||||
|
||||
- نقطة أصل الإحداثيات هي الزاوية السفلية اليسرى.
|
||||
- إذا كنت تستخدم خطاً مخصصاً (`font_file`)، تأكد من أنه ملف `.ttf` صالح.
|
||||
123
docs/edge/ar/tools/file-document/pdfsearchtool.mdx
Normal file
123
docs/edge/ar/tools/file-document/pdfsearchtool.mdx
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: بحث RAG في PDF
|
||||
description: أداة `PDFSearchTool` مصممة للبحث في ملفات PDF وإرجاع النتائج الأكثر صلة.
|
||||
icon: file-pdf
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `PDFSearchTool`
|
||||
|
||||
<Note>
|
||||
لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل.
|
||||
</Note>
|
||||
|
||||
## الوصف
|
||||
|
||||
أداة PDFSearchTool هي أداة RAG مصممة لعمليات البحث الدلالي داخل محتوى PDF. تتيح إدخال استعلام بحث ومستند PDF، مستفيدة من تقنيات بحث متقدمة للعثور على المحتوى ذي الصلة بكفاءة. هذه القدرة تجعلها مفيدة بشكل خاص لاستخراج معلومات محددة من ملفات PDF الكبيرة بسرعة.
|
||||
|
||||
## التثبيت
|
||||
|
||||
للبدء مع أداة PDFSearchTool، تأكد أولاً من تثبيت حزمة crewai_tools بالأمر التالي:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## مثال
|
||||
إليك كيفية استخدام PDFSearchTool للبحث داخل مستند PDF:
|
||||
|
||||
```python Code
|
||||
from crewai_tools import PDFSearchTool
|
||||
|
||||
# Initialize the tool allowing for any PDF content search if the path is provided during execution
|
||||
tool = PDFSearchTool()
|
||||
|
||||
# OR
|
||||
|
||||
# Initialize the tool with a specific PDF path for exclusive search within that document
|
||||
tool = PDFSearchTool(pdf='path/to/your/document.pdf')
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
|
||||
- `pdf`: **اختياري** مسار ملف PDF للبحث. يمكن تقديمه عند التهيئة أو ضمن معاملات طريقة `run`. إذا قُدم عند التهيئة، تقتصر الأداة في بحثها على المستند المحدد.
|
||||
|
||||
## النموذج والتضمينات المخصصة
|
||||
|
||||
بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي. ملاحظة: قاعدة بيانات متجهية مطلوبة لأن التضمينات المولّدة يجب تخزينها والاستعلام عنها من قاعدة بيانات متجهية.
|
||||
|
||||
```python Code
|
||||
from crewai_tools import PDFSearchTool
|
||||
|
||||
# - embedding_model (required): choose provider + provider-specific config
|
||||
# - vectordb (required): choose vector DB and pass its config
|
||||
|
||||
tool = PDFSearchTool(
|
||||
config={
|
||||
"embedding_model": {
|
||||
# Supported providers: "openai", "azure", "google-generativeai", "google-vertex",
|
||||
# "voyageai", "cohere", "huggingface", "jina", "sentence-transformer",
|
||||
# "text2vec", "ollama", "openclip", "instructor", "onnx", "roboflow", "watsonx", "custom"
|
||||
"provider": "openai", # or: "google-generativeai", "cohere", "ollama", ...
|
||||
"config": {
|
||||
# Model identifier for the chosen provider. "model" will be auto-mapped to "model_name" internally.
|
||||
"model": "text-embedding-3-small",
|
||||
# Optional: API key. If omitted, the tool will use provider-specific env vars
|
||||
# (e.g., OPENAI_API_KEY or EMBEDDINGS_OPENAI_API_KEY for OpenAI).
|
||||
# "api_key": "sk-...",
|
||||
|
||||
# Provider-specific examples:
|
||||
# --- Google Generative AI ---
|
||||
# (Set provider="google-generativeai" above)
|
||||
# "model_name": "gemini-embedding-001",
|
||||
# "task_type": "RETRIEVAL_DOCUMENT",
|
||||
# "title": "Embeddings",
|
||||
|
||||
# --- Cohere ---
|
||||
# (Set provider="cohere" above)
|
||||
# "model": "embed-english-v3.0",
|
||||
|
||||
# --- Ollama (local) ---
|
||||
# (Set provider="ollama" above)
|
||||
# "model": "nomic-embed-text",
|
||||
},
|
||||
},
|
||||
"vectordb": {
|
||||
"provider": "chromadb", # or "qdrant"
|
||||
"config": {
|
||||
# For ChromaDB: pass "settings" (chromadb.config.Settings) or rely on defaults.
|
||||
# Example (uncomment and import):
|
||||
# from chromadb.config import Settings
|
||||
# "settings": Settings(
|
||||
# persist_directory="/content/chroma",
|
||||
# allow_reset=True,
|
||||
# is_persistent=True,
|
||||
# ),
|
||||
|
||||
# For Qdrant: pass "vectors_config" (qdrant_client.models.VectorParams).
|
||||
# Example (uncomment and import):
|
||||
# from qdrant_client.models import VectorParams, Distance
|
||||
# "vectors_config": VectorParams(size=384, distance=Distance.COSINE),
|
||||
|
||||
# Note: collection name is controlled by the tool (default: "rag_tool_collection"), not set here.
|
||||
}
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## الأمان
|
||||
|
||||
### التحقق من صحة المسارات
|
||||
|
||||
يتم التحقق من مسارات الملفات المقدمة لهذه الأداة مقابل مجلد العمل الحالي. يتم رفض المسارات التي تحل خارج مجلد العمل وإطلاق `ValueError`.
|
||||
|
||||
للسماح بالمسارات خارج مجلد العمل (مثلاً في الاختبارات أو خطوط الأنابيب الموثوقة)، عيّن متغير البيئة التالي:
|
||||
|
||||
```shell
|
||||
CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true
|
||||
```
|
||||
|
||||
### التحقق من صحة الروابط
|
||||
|
||||
يتم التحقق من مدخلات الروابط: يتم حظر مخطط `file://` والطلبات التي تستهدف نطاقات IP الخاصة أو المحجوزة لمنع هجمات تزوير الطلبات من جانب الخادم (SSRF).
|
||||
89
docs/edge/ar/tools/file-document/txtsearchtool.mdx
Normal file
89
docs/edge/ar/tools/file-document/txtsearchtool.mdx
Normal file
@@ -0,0 +1,89 @@
|
||||
---
|
||||
title: بحث RAG في TXT
|
||||
description: أداة `TXTSearchTool` مصممة لإجراء بحث RAG (الاسترجاع المعزز بالتوليد) داخل محتوى ملف نصي.
|
||||
icon: file-lines
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## نظرة عامة
|
||||
|
||||
<Note>
|
||||
لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل.
|
||||
</Note>
|
||||
|
||||
تُستخدم هذه الأداة لإجراء بحث RAG (الاسترجاع المعزز بالتوليد) داخل محتوى ملف نصي. تتيح البحث الدلالي عن استعلام داخل محتوى ملف نصي محدد، مما يجعلها مورداً لا يُقدَّر بثمن لاستخراج المعلومات بسرعة أو العثور على أقسام محددة من النص بناءً على الاستعلام المقدم.
|
||||
|
||||
## التثبيت
|
||||
|
||||
لاستخدام `TXTSearchTool`، تحتاج أولاً إلى تثبيت حزمة `crewai_tools`. يمكن القيام بذلك باستخدام pip، مدير الحزم لـ Python. افتح الطرفية أو موجه الأوامر وأدخل الأمر التالي:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
سيقوم هذا الأمر بتنزيل وتثبيت TXTSearchTool مع أي تبعيات ضرورية.
|
||||
|
||||
## مثال
|
||||
|
||||
يوضح المثال التالي كيفية استخدام TXTSearchTool للبحث داخل ملف نصي. يعرض هذا المثال كلاً من تهيئة الأداة بملف نصي محدد والبحث اللاحق داخل محتوى ذلك الملف.
|
||||
|
||||
```python Code
|
||||
from crewai_tools import TXTSearchTool
|
||||
|
||||
# Initialize the tool to search within any text file's content
|
||||
# the agent learns about during its execution
|
||||
tool = TXTSearchTool()
|
||||
|
||||
# OR
|
||||
|
||||
# Initialize the tool with a specific text file,
|
||||
# so the agent can search within the given text file's content
|
||||
tool = TXTSearchTool(txt='path/to/text/file.txt')
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
- `txt` (str): **اختياري**. مسار الملف النصي المراد البحث فيه. هذا المعامل مطلوب فقط إذا لم يتم تهيئة الأداة بملف نصي محدد؛ وإلا سيتم إجراء البحث داخل الملف النصي المقدم مبدئياً.
|
||||
|
||||
## النموذج والتضمينات المخصصة
|
||||
|
||||
بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي:
|
||||
|
||||
```python Code
|
||||
from chromadb.config import Settings
|
||||
|
||||
tool = TXTSearchTool(
|
||||
config={
|
||||
# Required: embeddings provider + config
|
||||
"embedding_model": {
|
||||
"provider": "openai", # or google-generativeai, cohere, ollama, ...
|
||||
"config": {
|
||||
"model": "text-embedding-3-small",
|
||||
# "api_key": "sk-...", # optional if env var is set (e.g., OPENAI_API_KEY or EMBEDDINGS_OPENAI_API_KEY)
|
||||
# Provider examples:
|
||||
# Google → model_name: "gemini-embedding-001", task_type: "RETRIEVAL_DOCUMENT"
|
||||
# Cohere → model: "embed-english-v3.0"
|
||||
# Ollama → model: "nomic-embed-text"
|
||||
},
|
||||
},
|
||||
|
||||
# Required: vector database config
|
||||
"vectordb": {
|
||||
"provider": "chromadb", # or "qdrant"
|
||||
"config": {
|
||||
# Chroma settings (optional persistence)
|
||||
# "settings": Settings(
|
||||
# persist_directory="/content/chroma",
|
||||
# allow_reset=True,
|
||||
# is_persistent=True,
|
||||
# ),
|
||||
|
||||
# Qdrant vector params example:
|
||||
# from qdrant_client.models import VectorParams, Distance
|
||||
# "vectors_config": VectorParams(size=384, distance=Distance.COSINE),
|
||||
|
||||
# Note: collection name is controlled by the tool (default: "rag_tool_collection").
|
||||
}
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
74
docs/edge/ar/tools/file-document/xmlsearchtool.mdx
Normal file
74
docs/edge/ar/tools/file-document/xmlsearchtool.mdx
Normal file
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: بحث RAG في XML
|
||||
description: أداة `XMLSearchTool` مصممة لإجراء بحث RAG (الاسترجاع المعزز بالتوليد) داخل محتوى ملف XML.
|
||||
icon: file-xml
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `XMLSearchTool`
|
||||
|
||||
<Note>
|
||||
لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل.
|
||||
</Note>
|
||||
|
||||
## الوصف
|
||||
|
||||
أداة XMLSearchTool هي أداة RAG متطورة مصممة لإجراء عمليات بحث دلالي داخل ملفات XML. مثالية للمستخدمين الذين يحتاجون إلى تحليل واستخراج المعلومات من محتوى XML بكفاءة، تدعم هذه الأداة إدخال استعلام بحث ومسار ملف XML اختياري. من خلال تحديد مسار XML، يمكن للمستخدمين استهداف بحثهم بدقة أكبر نحو محتوى ذلك الملف، وبالتالي الحصول على نتائج بحث أكثر صلة.
|
||||
|
||||
## التثبيت
|
||||
|
||||
للبدء باستخدام XMLSearchTool، يجب أولاً تثبيت حزمة crewai_tools. يمكن القيام بذلك بسهولة بالأمر التالي:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## مثال
|
||||
|
||||
فيما يلي مثالان يوضحان كيفية استخدام XMLSearchTool. المثال الأول يوضح البحث داخل ملف XML محدد، بينما يوضح المثال الثاني بدء بحث بدون تحديد مسار XML مسبقاً، مما يوفر مرونة في نطاق البحث.
|
||||
|
||||
```python Code
|
||||
from crewai_tools import XMLSearchTool
|
||||
|
||||
# Allow agents to search within any XML file's content
|
||||
#as it learns about their paths during execution
|
||||
tool = XMLSearchTool()
|
||||
|
||||
# OR
|
||||
|
||||
# Initialize the tool with a specific XML file path
|
||||
#for exclusive search within that document
|
||||
tool = XMLSearchTool(xml='path/to/your/xmlfile.xml')
|
||||
```
|
||||
|
||||
## المعاملات
|
||||
|
||||
- `xml`: مسار ملف XML المراد البحث فيه. هذا معامل اختياري أثناء تهيئة الأداة ولكن يجب تقديمه إما عند التهيئة أو كجزء من معاملات طريقة `run` لتنفيذ البحث.
|
||||
|
||||
## النموذج والتضمينات المخصصة
|
||||
|
||||
بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي:
|
||||
|
||||
```python Code
|
||||
from chromadb.config import Settings
|
||||
|
||||
tool = XMLSearchTool(
|
||||
config={
|
||||
"embedding_model": {
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "text-embedding-3-small",
|
||||
# "api_key": "sk-...",
|
||||
},
|
||||
},
|
||||
"vectordb": {
|
||||
"provider": "chromadb", # or "qdrant"
|
||||
"config": {
|
||||
# "settings": Settings(persist_directory="/content/chroma", allow_reset=True, is_persistent=True),
|
||||
# from qdrant_client.models import VectorParams, Distance
|
||||
# "vectors_config": VectorParams(size=384, distance=Distance.COSINE),
|
||||
}
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
Reference in New Issue
Block a user